AD-A277  131 


Februarv  1994 


S.MC-93/1001  REV 


The  InldligerU  Monitoring  System 

Generic  Database  Interface  (GDI) 
User  Manual 


DTIC 

F  <  “CTE 
MAR  1  1994 


SPE<3ALTEC3^NK::AL  REPORT 
25  February  1994 
BasdineZl.l 


Jean  T.  Andetscsv  Mari  Moitefl,  Bonnie  MacRitdtie  Hbwaid  Turner 


Geophysical  Systems  Operation 


This  docuiaont  hcs  been  appxoved 
for  public  'alec.££  and  sole;  its 
distributioD  is  unlimited. 


The  vtowt  and  condudoni  contained  In  Ihh  document  aw  thoie  of  the  aulhois  and  ihotid  not  be  Intetpwted  at  representing  the  official 
pdlclet.elitwfexpiewed  Of  Implied,  ct  me  Adwneedneiei3whPro)eclt  Agency  Of  the  U.S.  Gowemment. 


Speeucndby. 

ADVANCED  RESEARCH  PROJECTS  AGENCY 

Nncker  Moniiofinc  Reteaich  Office 

ARPA  Older  Nnmber  6266,  PiQinm  Code  No.  627t4E 

ItmedbyiDARPA/CMO 

Coninct  No.  MDA972-92-C-0(n6 


’S  4  3  9 


Prindpel  Invet&iiior 
Or.  Thomas  C  Bache 
(619)4582531 


08  5  " 


94-07820 


REPORT  DOCUMENTATION  PAGE 


form  Apfifovtd 
0MB  No  0704  018$ 


•vWK  '•eo'Kxf  io»  n>-i  iau*<i<ox  o'  .»>o<"'*i'0»  i  lo  i  •>ou>  d<>  >naoxi>.  .xiiy^ix^  ik,  i,m«  lot  iniuiKiiext.  woxx-xa  ti-tnxo  ant  looxn 

'}«hor.At  M  maixIMXixf  IK*  Wl«  x«MM  (no  cox-We'-x^  1X0  ■»..,«.xo  IK,  (oM,niOX  0*  ixloixianox  ^XO  lOximoxll  imKixa  IXi,  «w«,n  nlixial,  0#  Jx,  otatl  IIOOCT  o'  '»•> 
lOi'fniox  o'  xno<x.«iiox.  .xiiuoixf  w<)4<xt'0xi  'o-  'Muoxo  ix.i  oo'Oox  10  oiiiK.xoiox  MoMananrit  s*'>Kn  0-Kiettia  'v  ix'oixioiiax  OM»i>oxt  <>4  ilTOoni  i<  H  i,m,'iox 
Ot<'|X.4Xx<,  Suit,  1)04  AlhxfIOX  il  );)0)4|0J  1X0  10  |X,  0"»,  O' W1-1<|,»,XI  1X0  Oudo,!  'iM'xiO'l  ■MurliOX  4f0|,n  (O’OO-O'U)  OOOlXix^lox  OC  )0M1 


t  AGfNCV  USt  ONLY  {Ltivf  bUnk) 


4.  TITLE  AND  SUBTITLE 


J.  REPORT  TYPE  AND  OATES  COVERED 

eclal  Technical  11/27/91-2/25/94 


5.  FUNDING  NUMBERS 


The  Intelligent  Monitoring  System 

Generic  Database  Interface  (GDI)  User  Manual 


S.  AUTHOR(S) 

Jean  Anderson,  Marl  Mortell,  Bonnie  MacRltchle, 
Howard  Turner 


7.  PERFORMING  ORGANUATION  NAME(S)  AND  AOORESS(ES) 
Geophysical  Systems  Operation 

Science  Applications  International  Corporation 
10260  Campus  Pt.  Drive 
San  Diego,  CA  92121 


MDA972-92-C-0026 


B.  PERFORMING  ORGANIZATION 
REPORT  NUMBER 


SAIC-93-1001REV 


9.  SPONSORING /MONITORING  AGENCY  NAME(S)  ANO  AOOflESS(ES) 

Advanced  Research  Project  Agency 
3701  N.  Fairfax  Drive,  //717 
Arlington,  VA  22203-1714 


10.  SPONSORING /MONITORING 
AGENCY  REPORT  NUMBER 


U.  ABSTRACT  (MitiimumtOOwordii 

The  Generic  Database  Interface  (GDI)  is  a  common  application  programmable 
to  multiple  databases,  providing  two  key  capabilities:  Database  access  and 
data  management.  Database  access  routines  allow  an  application  to  connect  to 
and  query  a  database  with  the  same  GDI  call  whether  the  target  database  is 
ORACLE,  POSTGRES,  or  SYBASE.  Data  to  and  from  the  database  are  managed  in 
the  native  format  of  the  application,  making  it  possible  to  provide  a  seamless 
integration  of  application  and  database. 


14.  SUBJECT  TERMS 


Data  Management,  Relational  Database,  Generic  Interface 


IS.  NUMBER  OF  PAGES 

140 


1«.  PRICE  CODE 


”■  OF^REPORT*’^”'''^^'®''  r*  OF^THiTpaGe”''''*^'®'*  I”  Of'aBSTRACt”'"'^*^'®''  '■''^'TATION  OF  ABSTRACT 

Unclassified  Unclassified  I  Unclassified  NONE 


NSN  7540  01 -ZBO-SSOO 


Standard  Form  29B  (Rev  2.69) 

4'n««M  •«  *Nii  Md  tlf.'l 

m.ioi 


Ota  Uttr  Manual 


Tabla  of  OoManta 


Table  of  Contents 


Parti:  Introduction 


1.  Overview . i-i 

1.1  Intended  Audience . 1-2 

1 .2  Document  Org^ization . 1  -2 

1 .3  User  Feedback . 1  -3 

2.  Architecture . 2-1 

2.1  Basic  Sen^ices . 2-2 

2-2  Database  Ccnnector  (dbConn) . 2-2 

2.3  Database  Object  (dbObj) . 2-3 

2.4  Comparison  to  Previous  Interfaces . 2-4 

2.5  Restrictions . 2-5 

Part  II:  Generic  Interface 

3.  Introduction . 3-1 

3.1  Location  of  GDI  Components . 3-i 

3.2  Sample  Programs . 3-2 

3.3  Database-Specific  Notes . 3-3 

3.3.1  ORACLE . 3-3 

3.3.2  POSTGRES . 3-4 

3.3.3  SYBASE . 3-4 

4.  Database  Communications  (dbConn) . 4-1 

4.1  Connecting  to  a  Database . 4-1 

4.2  Managing  Query  Channels . 4-5 

5.  Query  Execution . 5-1 

6.  Specialized  Database  Functions . 6-1 

7.  Data  Management  (dbObj) . 7-1 

7. 1  Tuple  Container. . 7-4 

7.2  Column  Definitions . 7-5 

7.3  Tuple  Constmctor . 7-7 


fi-i 


Azys'oSS 


!ty  Codes 

and  /  or 
eciai 


Baselne:  21.1 


□  n 


OaUttrUtnual 


Tabl*  ot  Oentmts 


8.  Error  Handling . 8-i 

8.1  User  Error  Functions . 8-2 

8.2  Low-Level  Error  Functions . 8-3 

8.3  Known  Problems . 8-4 

9.  Transaction  Management . 9-1 

Part  III:  High-Level  Interfaces 

1 0.  S-PLUS  Interface . 10-1 

10.1  Starting  S-PLUS . 10-2 

10.2  Connecting  to  a  Database . 10-3 

10.3  Executing  Database  Queries . 10-4 

1 0.4  Plotting  Results . 1 0-5 

1 0.5  T ransaction  Management . 1 0-6 

1 0.6  Exiting  S-PLUS . 1 0-6 

1 0.7  Summary  of  S-PLUS  Commands . 1 0-6 

1 1 .  FORTRAN  Interface . 11  -1 

11.1  Document  Organization . 11-1 

11.2  Subroutine  and  Function  Calls . 11-1 

11.3  Connecting  to  a  Database . 11-6 

11.4  Executing  Queries . 11-8 

11.4.1  Queries  that  Do  Not  Return  Data . 11-8 

11.4.2  Queries  That  Return  Data . 11  -9 

11.5  Handling  Errors . 11-11 

11.6  Sample  Programs . 11-12 

11.7  Troubleshooting  Tips . 11-14 

1 1 .8  Current  Restrictions . 1 1  -1 5 

Part  IV:  Reference  Manual 

utilities: 

gdi _gon_Astructs(1) . 1 

Generic  API: 

gdLabort(3) . 3 

gdLadd_ArrayStructs(3) . 4 

gdi_beginjtran(3) . 6 

gdLchannei_is_open(3) . 7 

gdi_close(3) . 8 

gdi_closo_channol(3) . 9 


Baseine:21.1  ii 


OaUmrtttnual  Tabit  of  OoimntB 


gdLcommit(3) . 10 

OdLd0ad(3) . 11 

gdij0rrorjlags(3) . 12 

gdi_errorjget(3) . 13 

gdLerrorJnlt(3) . 14 

gdLexit(3) . 15 

gdijlush(3) . 16 

gdi_get_aocount(3) . 17 

gdi_g0t_ArrayStrucls(3) . 1 8 

gdljg0t_count0r(3) . 21 

gdl_g0t_databas0(3) . 24 

gdl_g0t_dboption(3) . 25 

gdijg0t_nod0(3) . 27 

gdljg0t_v0ndors(3) . 28 

gdljnit(3) . 29 

gdijns0rt(3) . 30 

gdi_obLcr0at0(3) . 31 

gdi_obi_d0Stroy(3) . 32 

gdLop0n(3) . 33 

gdLop0njchann0l(3) . 35 

gdi_print_cold0fs(3) . 36 

gdi j)rint_conn(3) . 37 

gdi_print_dbobj(3) . 38 

gdi _print_tupl0S(3) . 39 

gdLrollback(3) . 40 

gdLsav0polnt(3) . 41 

gdLs0tjdboption(3) . 42 

gdi_sl00p(3) . 43 

gdljsubmit(3) . 44 

gdijrac0(3) . 48 

ORACLE-Spedfic  Routine: 

orad0_op0n(3) . 49 

ora_sqlca_0iTor(3) . 51 

FORTRAN  API: 

gdLclos0(3f) . 52 

gdL0rror_jg0t(3f) . 53 

gdL0iTorJnlt(3f) . 54 

gdijnlt(3f) . 55 


Ba8elne:21.1  ili 


QU  U99t 


nbl9of0onmnf 


gdLmap(3f) . 56 

gdi_open(3f) . 58 

gdl_submlt(3f) . 59 

gdl_trace(3f) . 61 

Part  V:  Appendices 

Appendix  A.  Bibliography . A-l 

Appendix  B.  Data  Types . B-1 


Ba8elne:21.1  iv 


OOf  UMf  Mmu^ 


Ovmvimtif 


1.  Overview 

The  Generic  Database  Interface  (GDI)  is  a  common  Application  Programming  Interface  (API)  to 
multiple  databases.  The  GDI  provides  two  Key  capabilities: 

1.  Database  Mcess 

An  application  connects  to  a  database  and  executes  a  database  query  with  the  same  GDI 
calls  whether  the  target  database  is  ORACLE,  POSTGRES,  or  SYBASE. 

2.  Data  Management 

Data  to  and  from  the  database  are  managed  in  the  native  format  of  the  application,  mak¬ 
ing  it  possible  to  provide  a  seamless  Integration  of  application  and  database. 


The  GDI  model  consists  of  the  components  depicted  in  Figure  1.  High-Level  interfaces  may  be 
added  without  having  to  modify  lower  level  functionality. 


FIGURE  1.  Generic  Database  Interface  (GDI)  Model 


Working  from  the  bottom  of  Figure  1  to  the  top.  the  GDI  consists  of: 

•  Database  Interface 

Manages  interaction  with  the  target  database. 

•  Generic  Interface 

Provides  a  common  API  for  C  applications  to  access  any  database  and  manage  data. 

•  High-Level  Interfaces 

Support  programming  lanouages  such  as  FORTRAN  and  Scheme,  and  teird-party 
products  such  as  S-PLUS. ' 


Basefine:21.1 


1-1 


OU  Uttr  Manual 


1.1  Intended  Audience 

The  GDI  targets  two  types  of  users:  the  ernt-i^r  and  the  application  developer.  Section  10 
describes  S-PLUS.  an  end-user  application. 

The  end-user  interactiveiy  accesses  the  database  with  a  program  created  by  an  application 
developer  or  a  third  party  tool  such  as  S-PLUS.  End-users  want  a  Tiot  link”  between  the  applica¬ 
tion  and  the  target  database  so  they  can  concentrate  on  research  and  analysis.  They  do  not  want 
to  be  sidetradted  by  having  to  manually  transfer  data,  not  even  with  the  aid  of  data  migration 
tools. 

The  application  developer  writes  programs  that  rec^ire  database  access.  Application  developers 
want  a  consistent  interface  between  the  application  and  the  target  database  so  they  can  concen¬ 
trate  on  a  specific  area  of  programming  expertise,  whether  it  be  the  design  of  sophisticated  user 
interfaces  or  complex  scientific  programs.  They  do  not  want  to  be  sidetracked  by  having  to  learn 
how  to  access  each  database. 

Neither  user  wants  to  become  an  expert  for  each  database  accessed.  Both  want  application  and 
database  to  be  transparently  integrated.  The  GDI  achieves  that  transparent  integration. 

This  manual  describes  what  each  user  must  know  to  submit  queries  to  a  database  and  manage 
data.  The  user  needs  to  know: 

•  The  database  query  language,  which  is  a  topic  beyond  the  scope  of  this  document. 
Appendix  A  lists  a  few  SQL  references.  POSTGRES  documentation  is  available  via 
anonymous  ftp  from  postgres.berkeley.edu. 

•  How  to  use  the  generic  luncUons  that  execute  queries  arrd  manage  data.  This  is  the 
topic  of  this  manual. 

The  user  does  not  need  to  know: 

•  Database  vendor-specific  implementation  of  Embedded  SQL  and/or  the  call  interface. 

•  Database  vendor-spedfic  data  dictionary  structure. 

•  Database  vendor-specific  error  handling. 

•  Application-specific  and  database-specific  data  formats. 

•  Internal  GDI  data  structures. 


1.2  Document  Organization 

PART  I  introduces  a  high-level  view  of  the  GDI.  Section  1  (this  section),  describes  the  GDI  model. 
Section  2  describes  the  GDI  architecture. 

PART  II  introduces  GDI  routines  to  the  application  developer.  Section  3  discusses  naming  con¬ 
ventions,  sample  programs,  and  known  problems.  Section  4  discusses  database  communica¬ 
tions.  Section  5  and  Section  6  describe  query  execution  and  specialized  database  functions. 


1 .  S-PLUS  is  a  statistical  and  graphics  program  developed  by  StatSd  that  is  based  on  the  S-Lan- 
guage. 
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Section  7  describes  data  manaoement.  Section  8  and  Section  9  discuss  error  hamtiing  and 
transaction  management  respectively. 

PART  III  introduces  the  high-level  interlaces  to  the  end-user.  Section  10  contains  an  S-PLUS 
tutorial.  Section  11  describes  the  FORTRAN  interface. 

PART  IV  contains  UNIX  Section  1  man  pages  for  GDI  tools  and  Section  3  man  pages  for  GDI 
routines.  The  most  current  man  pages  are  available  on-line. 

PART  V  contains  appendices.  Appendix  A  is  a  bibliography  of  SQL  language  references.  Appen¬ 
dix  B  Is  a  description  of  GDI  data  types. 

1.3  User  Feedback 

The  GDI  development  team  welcomes  comments.  All  bug  reports  and  suggestions  for  improve¬ 
ment  should  be  sent  to  gcli@gso.saic.com. 
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2.  Architactura 

Section  1  presented  a  high  level  viow  of  the  QOI.  This  section  describes  the  key  components  of 
the  GDI  architecture: 

•  Basic  Senecas:  Database  access  routines. 

•  Database  Connector  (dbCorm):  Manages  database  queries. 

•  Database  Manages  data  to  and  froin  the  database. 

Figure  2  depicts  how  an  appUcation  uses  the  dbCorm  and  dbObj  to  access  a  database.  All  que¬ 
ries  are  executed  on  the  dbConn  that  was  established  when  the  appUcation  connected  to  the 
database.  This  is  similar  to  a  C  program  using  a  FILE  pointer  for  reads  and  writes  to  a  file  opened 
with  topenQ.  If  a  query  returns  the  GDI  returns  a  pointer  to  the  dbOb)  containing  the  data.  If 
an  application  needs  to  insert  data  into  the  database.  It  can  create  a  dbOt^  and  populate  it  with 
the  data  to  be  inserted. 
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2.1  Baste  S^rvICM 

GDI  routines  are  organized  into  the  following  areas  that  provide: 

1.  ComnujnicaOom 

Database  opens  and  doses,  query  cancellation,  and  query  tradng. 

2.  Error  HandUng 

Consistent  error  reporting  whether  the  actual  error  was  a  rfatahanA  error,  a  UNIX  error,  or 
an  application-specific  error.  The  application  can  decide  whether  warnings  should  be 
treated  as  fatal  and  a  debug  option  automatically  outputs  errors  to  siderr  to  aid  develop¬ 
ers  in  debugging  problems. 

3.  Transaction  Managamant 

Hooks  for  starting  a  multi-statement  transaction  (POSTQRES  and  SYBASE),  and  for 
issuing  commits,  rollbacks,  and  savepokits. 

4.  Data  Dictionary  Aocass 

Consistent  interface  to  each  vendor's  data  dictionary  for  commonly  asked  questions  such 
as  '>Mhat  is  this  object?".  'Vrhat  is  its  structure?".  ‘Yrho  owns  it?” 

5.  Carmad  Databasa  Quarias 

Highly  optimized  database  access  for  commonly  required  functionality.  For  example, 
some  vendor  products  have  sequendng  mechanisms  while  others  do  not  The  g<S_siat_- 
countarO  routine  provides  a  highly  optimized,  consistent  mechanism  for  fetching  unique 
id’s  regardless  of  database. 

6.  Dynamic  Quarias 
Support  for  dyr«mic  queries. 

7.  Data  Managamant 

Data  are  managed  in  native  application  data  format 

2.2  Database  Connector  (dbConn) 

The  Database  Connector  (dbConn)  manages  queries.  When  an  application  connects  to  the  data¬ 
base.  the  GDI  aeates  a  dbConn  that  keeps  track  of  administrative  information,  such  as: 

•  database  vendor  type  {La..  ORACLE.  POSTGRES,  SYBASE) 

•  database  name,  account,  and  node 

•  error  information  for  the  last  query  executed  (specific  database  error  code  and  string) 

A  single  application  can  have  multiple  dbConn's,  consisting  of  multiple  connections  to  the  same 
database  or  to  a  mixture  of  databa^,  as  depicted  in  Figure  3.^ 


1.  Only  one  cormedion  to  POSTQRES  is  aNowed  at  this  time,  txit  an  applicalion  may  mix  one  POST¬ 
GRES  connection  with  many  ORACLE  and  SYBASE  connections. 
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The  dbConn  also  keeps  track  of  the  query  channel,  a  communications  "pipo”  on  which  database 
queries  are  managed  and  executed.  A  channel  is  a  DBPROCESS  for  SYBASE,  a  cursor  for 
ORACLE,  and  a  portal  for  POSTGRES.  Each  dbConn  is  initialized  with  at  least  one  channel  for 
default  query  activity,  but  users  may  add  as  many  channels  as  they  like,  as  depicted  in  Figure  4. 


FIGURE  4.  Datifoase  Ckiary  Channala 
2J3  Database  Object  (dbObJ) 

The  Database  Ot^ect  (dbObj).  depicted  In  Figure  5,  manages  data  and  is  composed  of  the  fol¬ 
lowing  internal  structures: 

•  Tqpfo  Container 

Stores  the  data,  which  might  be  query  results  from  a  SELECT  (outputs),  or  data  to  be 
inserted  into  the  database  (inputs).  By  default,  data  are  organized  into  rows  and  col¬ 
umns.  like  a  database  table.  The  exact  organization  is  controlled  by  the  Tuple  Con¬ 
structor. 

•  Column  Definitions 

Describes  each  column  in  the  tuple  container,  including  name,  data  type,  and  length. 

•  Tuple  Constructor 

Specifies  how  to  manage  data  in  the  tuple  container.  For  example,  S-PLUS  operates 
on  columns  and  rows  instead  of  on  rows  and  columns.  The  S-PLUS  custom  interface. 
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described  in  Section  10.  uses  an  S-PLUS  tuple  constructor  instead  of  the  default  tuple 
constructor.  While  the  specific  data  format  is  intended  to  be  transparent  to  the  end- 
user.  Section  7.3  describes  how  programmers  may  create  tuple  constructors  to  fit  a 
particular  application  need. 

•  Query  Mormation 

Retains  query  information,  such  as  the  database  query  string,  whether  or  not  the 
query  succeeded,  and  how  many  rows  were  affected.  The  dbOb|  retains  general  GDI 
information  with  each  result  set  while  the  dbConn  stores  specific  database  error  infor¬ 
mation  about  the  last  query  executed. 


r 


Tuple  Container  | 

1 

Column  Definitions  || 

dbObJ 

1 

Tuple  Constructor  || 

1  ^ 

Query  Information  || 

FIGURE  5.  Database  Obiact  (dbObO 

The  GDI  provides  functions  and  macros  for  accessing  a  dbObj.  The  user  does  not  need  to  know 
the  internal  structure. 

2.4  Comparison  to  Previous  Interfaces 

SAIC  has  developed  several  database  library  interfaces.  They  supported  the  most  basic  data¬ 
base  services,  the  first  five  items  discussed  in  Section  2.1.  But  none  of  them  supported  fully 
dynamic  queries  and  data  management,  resulting  in  two  fundamental  flaws: 

•  Libraries  were  Schema-Driven. 

•  Data  structures  were  inflexible. 

This  section  describes  how  the  dbObj  solved  both  these  problems. 

Schema-Driven  Ubrariee 

Fully  dynamic  database  selects  were  difficult  to  support  because  fliere  was  not  a  straight-forward 
way  to  pass  dynamic  query  results  back  to  the  calling  application.  Instead,  insert  and  fetch  rou¬ 
tines.  with  the  corresponding  C  and  FORTRAN  program  headers,  were  generated  automatically 
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for  each  table  based  on  its  definition  in  the  database,  if  the  structure  of  the  database  changed, 
the  push  of  a  button  wouid  regenerate  the  support  library. 

In  essence,  the  database  access  library  was  hard-coded  to  the  schema  being  accessed,  an 
approach  that  had  serious  limitations: 

•  Poor  &jpport  for  New  or  Changing  Database  Structures 

Appiications  could  not  access  newly  created  tables  until  headers  and  routines  had 
been  generated,  the  library  remade  and  reinstalled,  and  the  application  recompiled. 
Modifying  existing  tables  required  synchronizing  changes  to  database  tables,  access 
libraries,  program  headers,  and  the  applications.  The  library  became  a  weak  link 
between  the  application  and  the  database. 

•  Inflexible  SELECT  Usts 

Since  the  SELECT  list  was  hard-coded  to  a  single  table,  an  application  received  all 
fields  in  a  table  even  if  it  wanted  Just  one.  More  Importantly,  an  application  queried 
one  table  at  a  time,  even  though  it  might  need  data  from  many  tables.  The  application 
had  to  select  from  each  table  separately,  then  merge  the  results.  Because  of  this,  the 
number  of  application-specific  routines  grew,  defeating  one  of  the  primary  purposes  of 
a  centralized  library  which  is  to  reuse  code. 

The  dbObj  overcomes  the  problem  of  managing  dynamically  defined  query  results.  Appiications 
may  access  new  tables  as  soon  they  are  created,  access  existing  tables  as  they  are  changed, 
and  execute  any  database  statement  that  is  legal  for  the  target  database. 

Inflexible  Data  Structures 

Previous  interfaces  supported  one  data  structure:  an  array  of  stnictures.  If  an  application  needed 
a  linked  list,  it  constructed  the  list  and  copied  the  data  into  it  Likewise,  data  were  copied  to  FOR¬ 
TRAN  storage.  Loading  data  into  S-PLUS  required  dumping  results  to  a  fiat  file,  then  manually 
descrtt}ing  and  loading  the  file  into  S-PLUS.  Too  many  steps  were  required  to  migrate  or  copy 
data  into  the  application. 

The  dbObj  reduces  data  copying  by  supporting  the  application  structure  directly. 

2.5  Restrictions 

While  an  application  may  attach  to  multiple  databases  simultaneously,  no  effort  is  made  to  trans¬ 
late  queries  for  the  target  database;  the  GDI  passes  the  query  straight  through. 

SQL  Support 

Commerdai  relational  databases  extend  the  ANSI  SQL  standard  with  features  that  are  not  guar¬ 
anteed  to  work  with  other  products.  For  example,  a  query  containing  the  ORACLE  outer  Join 
operator  (•••)  will  fail  if  it  is  sent  to  a  SYBASE  database  which  uses  the  asterisks  (*)  as  the  outer 
Join  operator. 

The  GDI  passes  database  queries  directly  to  the  database,  it  does  not  parse  nor  translate  que¬ 
ries  to  another  vendor’s  SQL  dialect  Vendor-specific  features  should  be  avoided.  Appendix  A 
notes  which  references  describe  ANSI  SQL 
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Transaction  manaoement  and  query  channels  are  handtod  dtterentty  by  the  various 
vendors.  Some  functions  are  only  applicable  to  a  subset  of  the  supported  databases.  Other  func¬ 
tions  have  different  effects  depending  on  the  target  database. 
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3.  Introduction 

This  part  of  the  GDI  User  Manual  describes  the  functions  that  provide  the  foUowing  capabilities  to 
an  appiication  deveioper:  The  appiication  developer  must  know  C  and  SQL 

•  Database  communications 

•  Query  execution 

•  Spedaiized  database  functions,  such  as  unique  key  assigtvnent  and  data  dictionary 
access 

•  Transaction  Management 

•  Error  handling 

3.1  Location  of  GDI  Components 

Table  1  summarizes  the  location  of  GDI  components.  INSTAU.  refers  to  the  directory  tree  where 
software  is  normally  installed  for  production  access.  UBSRC  refers  to  the  directory  containing 
library  source  code. 


Tablet.  Summary r^Locatioiis 


Name 

Description 

Directory  Location 

User  Manual 

FramaMakar'  souioa  organizad  into  a  book 
namad  gCLtk.  A  Postscript  varsion  is  nantad 

USSnCflk)gandbtooc/fmAJ8ar_manual 

manpagas 

UNIX  man  papas  dascriba  aach  GDI  function 
can. 

INSTALUrrum 

li)gdLa.  lbgdiora.a 

GDI  Ibrarias  linkad  in  by  an  iV)piication 

INSmuAb 

ttigdi.h.  gdijr77.h 

Public  GDI  haadais  that  appicalions  inchjda  in 
aoiHoaoodafilas. 

MSTAU/incfcida 

gdi_gan_Attnjcts 

Haadar  ganarator  tor  ArrayStructs  tupla  con¬ 
structor;  saa  gdi_gan_Astructs(1). 

INSTALUbin 

unit  lasts  and  sampia 
coda 

Unit  lasts  that  axaicisa  and  damonstrata  GDI 
functions. 

l/eSRCilbgandbAast 

FORTRAN  unft  lasts 

Unit  lasts  tfiat  axaicisa  and  damonstrata  tha 
FORTRAN  intarfaca. 

ueSROIbgandb/last 

souicaooda 

GDI  functions. 

UBSRC/Vbgendb/vc 

1.  Frameinalar  is  a  (kKument  puUufaing  tool  Cpoin  Frarae  Tecfandogy  Coipontion 
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ZJ2  Sampto  Programs 

The  programs  in  L/BSRC^bgenctti/test  exercise  QOI  functions  and  constitute  sample  code  that 
demonstrate  how  to  use  the  GDI.  Table  2  summarizes  the  test  programs. 


Tbblel.  GDI  Samirfe  Programs 


Program 

DescripHon 

intsrictjiutMnit 

TMtsttw  (xfLMtxiWrofuncten  fay  pioinpline  for  input  interadivaV. 

tst_ArrayStnicU_subfflil 

tst.ArrayStrucUJnMft 

Tatts  tha  ArrayStructo  tupla  oonatruckM.  which  inaiuie*s  data  in  an  array 
of  structuraa. 

tstjoonn 

Taata  datahtaa  oonnaet  functions. 

tstjoonstr 

Tasts  constructor  functions. 

tStjCTMt* 

Craatas  a  tamporary  tabla  in  tha  databasa. 

tttjitoobj 

Tasts  dbObj  functiona. 

tst_g«t_oount*r 

Tasts  ths  gdi_gtijooufa»r()  routina. 

tstjg«t_dboount 

Tasts  Oracta  PnO*C  hooks,  raquiras  databasa  opan  with  onckuopMO- 

tstjnicftl 

Fatchas  data  from  tha  datsbasa  and  insarts  it  into  anothar  tabla  In  tha 
dtrtshssa 

tstJriMitZ 

Craatas  a  dbObj  and  populatas  it  with  data  that  it  than  insarts  Hito  tha 

datsbasa. 

tst.submit 

Tasts  tha  gdi_mjbmMO  function. 

tst.wtiaiis 

Tasts  ths  0d!Lwfiar_fs_oq|bcff>function. 

The  programs  use  Ubpar.a,  a  public  domain  Ibraiy  from  Caltech,  to  parse  command  line  argu¬ 
ments.  The  command  line  arguments  can  be  included  in  a  parameter  file  (e.g.  par  file)  and  the 
name  of  the  this  file  can  be  used  on  the  command  line.  A  par  file  for  each  test  program  resides  in 
i./BS/7Cyiibgendb/test.  Additional  par  files  are  ^  L/B5BCsni)gendb/lest/|par.  These  par  files  access 
project-specific  databases  used  during  GDI  development  and  testing.  They  should  be  checked  to 
make  sure  accounts,  passwords,  database  names  and  queries  are  appropriate  for  the  local  data¬ 
base. 
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Instructions  for  compiling  and  executing  each  test  stub  are  based  on  the  source  code  filename 
(Table  3). 


lUricB.  Test  Stub  Instructions 


General  Instmcbona 

Example 

SouiccCod* 

pnvnvn.fMflMLC 

Mjoonnx 

PwRI* 

pmgamjnemeeet 

tatjoonn^MT 

To  Compile 

malM  p0ogmm_name 

make  Mjoonn 

ToExocuto 

pmgmm_neme  f>atmpngnm_nemeeer 

tUjoonn  pv>t«t_oonn.par 

3^  Database-Specific  Notes 
3^.1  ORACLE 


3.3.1. 1  Comf^ling  Applications 

Applications  must  link  UbgtMM  with  an  ORACLE-spedfic  library.  Ibgctonua,  and  with  ORACLE 
libraries  at  revision  6.0.36.4  or  higher  because  new  Orade  Call  Interface  (OCI)  functions  used  by 
the  GDI  became  available  in  that  release.  As  of  thte  writing,  the  fdlowing  6.0.36.4  libraries  must 
be  linked  (see  the  san^  Makefile  in  ifBSRCAibgendb/test): 

libod14c.a  OCI  routines 

Iibsql14.a  PRO*C  routines 

libsqlneLa  SQL*Net  libraiy 

libora.a  ORACLE  RDBMS  kernel  routines 

Once  compiled  with  6.0.36.4,  the  application  may  be  used  with  ORACLE  databases  running  an 
earlier  revision.  It  has  been  used  extensively  with  6.0.33.2  databases. 

3.3. 1.2  Support  for  PRO*C  ftouOnes 

Currently,  gcSjop&nQ  establishes  database  connections  with  OCI.  This  allows  multiple,  concur¬ 
rent  connections  for  applications  using  the  GDI  or  their  own  OCI  functions.  Applications  may  link 
in  their  own  PRO*C  sdxoutine;  but  they  must  first  establish  a  PRO*C  datdt>ase  connection  with 
the  GDI  function  oradejopenQ  (see  oracle_open(3)).  PRO*C  subroutines  must  be  executed  on 
that  ocnnection.  Due  to  a  limitation  of  Orade  version  6.  only  one  PRO*C  connection  may  cur¬ 
rently  be  opened  at  a  time.  However,  additional  OCI  connections  may  be  established  with  gdi_o- 
pen().  A  future  enhancement  will  allow  muitipie  PRO*C  connections. 

A  low-level  error  handling  routine,  ora_sqlca_error(),  provides  deveiopeis  of  PRO*C  routines  with 
the  ability  to  store  SQLCA  error  information  in  the  dbObj  (see  ora_sqtca_error(3)).  Example  1 
shows  sample  calling  syntax. 
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Example  1: 

EXEC  SQL  OPEN  my_cursor: 

if  (ora  aqica  arror  (conn,  sqlca.  *my  cursor  open:  *)  U  QOI_SUCCESS) 

7aturnT60LFAILURE); 

orp_count4x  in  L/BS/7Cyiibgendb/te8t  demonstrates  the  PRO*C  capabiUty.  tst_get_dbcount  in 
L/SSffC^ibgendb/test  exercises  the  PRO*C  function. 

3.3.1. 3  CsJculated  Numbers  are  Doubles 

Calcuiated  coiumns  will  be  returned  as  doubles,  even  if  the  result  is  an  integer.  For  example,  the 
following  query  will  return  count  ea  a  double: 

salact  count(wfid)  count  from  wfdisc  whara  wfid  >  50(X)0 


3.3.1. 4  fnxed  Date  Format 

The  default  ORACLE  date  format  contains  only  the  date  (year,  month,  day);  it  does  not  include 
time  (hours,  minutes,  seconds).  Version  6  does  not  aHow  setting  a  different  default  date  format; 
although,  that  capability  will  be  available  Version  7.  Until  Version  7  becomes  widely  available,  the 
following  ORACLE  date  format  will  be  expected  throughout  the  GDI: 

YYYYMMDD  HH24:MI:SS 

Later  versions  of  the  GDI  will  be  able  to  support  user-defined  date  formats. 

3.3.1. 5  Link  System  V 

Developers  can  compile  applications  any  way  they  like,  but  the  final  link  must  be  System  V  rather 
than  BSD.  If  a  segmentation  fault  occurs  on  a  database  select  inside  a  lower  level  ORACLE  rou¬ 
tine,  the  application  is  probably  resolving  s^nbols  from  Ajsr/lij^lbc.a  instead  of  /usr/5lk>/lkK.a. 

3-3,2  MONTAGE 
Basic  hooks  are  in  place. 

3.3.3  POSTGRES 
Basic  hooks  are  in  place. 

3J3A  SYBASE 
Basic  hooks  are  in  ptex». 
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4.  Database  Communications  (dbConn) 

Table  4  summarizes  the  database  communications  functions. 


1^516  4.  Summary  of  Communication  Functions 


Name 

Description 

ManPage 

SampleCode 

gdi_inll 

Mtialza  Iha  GDI  Ubrary 

gdLMtp) 

tatjoonn.c 

gdi.opan 

Eatabtiahaa  a  oonnaction  to  tha  databasa. 

gdi.opanO) 

tat_oor)n.c 

gdi_doM 

Cloaaa  a  oonnaclion  to  tha  databaia. 

gdijBioaa(3) 

tatjoonn.c 

gdLaxit 

Cioaaa  al  dnabaaa  oonnaoliona. 

gdi_axil(3) 

tat_oonn.c 

gdijdaad 

Chaoka  to  aaa  1  oonnaclion  ia  Nva. 

gdijdaadfS) 

gdi _priiitjoonn 

Oulputa  oontonta  of  dbConn  to  atdoiA 

gdi_printjoonn(3) 

t8t_oonn.c 

oradajopan 

Opana  an  Orada  PnO*C  oonnaclion 

oradajopanfS) 

tatjgaljdboountc 

gdijopanjctiannal 

Opana  an  additional  query  channaL 

gdi_opanjcharmal(3) 

tat_oonn.c 

gdi_doaa_channal 

Ciooaa  tha  apacHiad  query  charmaL 

gdijcioaajchannai(3) 

tat_conn.c 

gdi_ctwnnal_isjopan 

Chacka  to  aaa  if  channel  ia  atil  open. 

gdijchannal_iBjopan(3) 

gdi_abort 

liNininalaa  tha  currant  command. 

gdLabort(3) 

gdLfkiah 

Diicarda  unpreoaaaad  query  raaulta. 

gdijluah(3) 

4.1  Connecting  to  a  Database 

gdiJnitO  initializes  the  GDI  Ibrary.  It  takes  two  parameters: 
appname  Name  of  the  executable. 

gdihome  Root  directory  of  GDI  installation.  The  GDI  searches  gdhome/lib  for 
shared  objects  it  dynamically  loads. 

gdiJnitO  should  be  called  once  by  the  application  program  before  any  other  GDI  functions  are 
called. 

Example  2: 

gdijnit  (argv[0],  ‘/pri/tharad/lib”); 
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gdLopenO  connects  a  process  to  a  database  and  returns  a  dbCorm  structure.  A  NULL  dbConn 
means  the  connect  failed.  Table  5  summarizes  which  databases  use  each  parameter. 


TibleS.  gdi_openO  Paramders 


Parameter 

MONTAGE 

ORACLE 

POSTQRES 

SYBASE 

vendor 

yea 

yea 

yea 

yea 

account 

optional 

yea 

no 

yea 

paaswrord 

optional 

optional 

no 

yea 

databaae 

optbrud 

optional 

optional 

yea 

aenrer 

optional 

no 

yea 

appname 

no 

no 

no 

yea 

Example  3  shows  how  a  program  called  SampleProgram  might  connect  to  an  ORACLE  data¬ 
base. 

Examples: 

dbConn  *my_dbConn1 ; 

char  *vandor«'oracla”; 

char  *account>‘scott*; 

char  *paatword>*tigar*; 

char  ‘db-tthoatl  -.daV;  r  ORACLE  Varaion  6  SQL*Hat  TWO.TASK  atring  */ 

if  ((my.dbConnI  >  gdLopan  (vendor,  account,  paaaword,  db,  NULL,  NULL)  >*  (dbConn  *)  NULL) 

...  handle  error ... 

) 

The  last  two  gdi_open()  parameters  are  NULL  because  they  are  not  used  for  connecting  to  ORA¬ 
CLE.  Also,  if  the  account  parameter  contains  the  entire  ORACLE  connect  string,  the  rest  of  the 
parameters  may  be  left  NULL  Example  4  would  create  the  same  database  login  as  Exarr^ie  3. 

Example  4: 

dbConn  *my_dbConn1 ; 

char  *vendor>'oracle'’; 

char  *acoount-*acottAigar9t:hoat1  :dav”; 

if  ((my.dbConnI  -  gdi_opon  (vendor,  account,  NULL.  NULL.  NULL,  NULL)  --  (dbConn  *)  NULL) 

...  handle  error ... 

) 

At  this  point  SampleProgram  is  now  connected  to  one  database,  as  depicted  in  Figure  6. 
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An  application  niay  connect  to  more  than  one  database  simultaneouaiy.  Example  5  shows  the 
same  process  connecting  to  a  POSTGRES  database. 

ExannpleS: 

dbConn  *ffly_dbConn2; 

char  *vandor«*poatgras*; 

char  *accounUNULL: 

char  *paaaword-NULL 

char  'db-’gdidamo*; 

char  *aarvaraNULi.; 

char  *app-NULL; 

((n)y_dbConn2  •  gdi  opan  (vendor,  account,  password,  db,  sarvar,  app)  >■  (dbConn  *)  NULL) 

{ 

...  handle  error ... 

) 

The  database  host  will  be  driven  by  the  POSTGRES  PGHOST  environmentai  variable.  Sam- 
pieProgram  is  now  connected  to  two  databases,  as  depicted  in  Figure  7. 


FIGURE  7.  SampleProgram  Connected  to  IWo  Databases 
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Each  dbConn  keeps  track  of  database  login  information,  error  infonnation  and  some  vendor-spe¬ 
cific  information.  The  contents  of  the  dbConn  may  be  output  with  gdl _print_conn().  Example  6 
shows  how  the  dbConn  connections  established  by  Example  4  and  Example  5  could  be  output  to 
stdout. 

Examples: 

gdi _print_conn  (my.dbConnl); 
gdi _print_conn  (my_dbConn2); 

The  connection  to  the  database  could  be  broken  for  a  variety  of  reasons  (network  down  or  too 
unreliable  to  sustain  a  connect,  database  down,  database  host  crashed.  Just  to  name  a  few). 
gdLdeadO  determines  if  a  dbConn  is  stiii  alive.  It  is  executed  on  a  specific  query  channel,  which 
is  described  more  in  Section  4.2. 

Example  7: 

if  (gdi.daad  (my  dbConn  1,  channal)  >■  TRUE) 

{ 

...  connaetion  droppad,  do  aomathing  appropriata  ... 

) 

gdijdoseO  doses  a  specific  database  connection.  Example  8  doses  my_dbConn"\ ;  but  myjdb- 
Conn2  remains  open. 

Example  8: 

gdi.cloaa  (my.dbConnI); 

gdijBxItO  doses  alt  open  connections.  Example  9  doses  both  my_dbConnr\  and  my_dbConn2. 
Example  9: 
gdi_axH  (); 
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4J2  Managing  Qutry  Channels 

in  ackitlon  to  storing  login  and  error  infonnation,  the  dbConn  also  tracks  query  channels,  “pipes” 
on  which  database  commands  get  executed. 

Query  channels  are  analogous  to  UNIX  shells: 

•  UNIX  shell 

After  logging  into  a  UNIX  workstation,  a  user  executes  UNIX  commands  in  a  shell. 

The  workstation  might  be  running  a  window  rrwnager  such  as  Motif  that  allows  creat¬ 
ing  additional  windows.  Used  together,  multiple  windows  make  the  Job  at  hand  more 
efficient  The  UNIX  login  to  the  workstation  keeps  track  of  the  shells.  If  the  login  goes 
away,  all  the  shells  disappear. 

•  Database  query  channel 

After  logging  into  a  database,  a  process  executes  database  commands  on  a  query 
channel.  GDI  functions  allow  the  creation  of  additional  channels.  One  channel  might 
be  used  to  read  a  large  amount  of  data  from  the  database.  A  second  channel  might 
update  a  table  based  on  information  read  from  the  first  The  (tt)Conn  keeps  track  of 
the  query  channels.  If  the  dbConn  disappears,  ail  the  query  channels  disappear. 

gdl_open()  creates  detault  query  channels  that  are  managed  by  GDI  routines.  If  an  application 
uses  just  GDI  routines,  it  does  not  need  to  do  anything  with  query  channels. 

Applications  that  add  database  routines  may  need  to  know  about  query  channels,  infonnation 
provided  by  the  rest  of  this  section. 

Each  channel  equates  to  an  MLCONNECTION  for  MONTAGE,  a  cursor  for  ORACLE,  a  portal 
for  POSTGRES  (if  a  fetch  is  inv^ed),  and  to  a  DBPROCESS  for  SYBASE.  g<Mjopen()  creates 
two  query  channels  with  the  loose  notion  that  one  is  for  reading,  the  other  for  writing,  libgdi.h 
defines  aliases  for  accessing  these  two  channels.  The  first  channel  may  be  used  by  specifying 
GDI_DEFAULT_CHAN  or  GDi_SELECT_CHAN.  The  second  may  be  used  by  specifying  GDI_- 
UPDATE_CHAN. 

The  GDI  attempts  to  provide  consistent  handling  across  databases,  but  this  is  not  always  possi¬ 
ble.  Sometimes  a  query  channel  makes  sense  for  one  database  but  not  another.  For  example. 
ORACLE  manses  transactions  at  the  dbConn  level  while  SYBASE  manages  them  at  the  chan¬ 
nel  level.  Example  10  shows  how  variable  handling  may  be  accommodated  in  an  application. 

Exsarple  10: 
fifdsf  SYBASE 

ehanno  «  QDLDEFAULT.CHAN; 

*«Im 

ehanno  -  GOLNOT.USED; 

•andH 

If  a  query  channel  is  specified  for  a  function  which  operates  at  the  connection  level  for  that  data¬ 
base.  such  as  gdi.rollbackO  or  gdi.oommitO.  then  the  channel  argument  will  be  Ignored  and  the 
operation  will  be  performed  for  the  entire  connection.  This  may  cause  confusion  for  applications 
switching  between  different  database  back-ends,  such  as  ORACLE  and  SYBASE. 
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Example  11  creates  an  additional  query  channel.  Note  that  the  addressof  the  new  query  channel 
number  should  be  passed  to  gdijopen__channet().  The  GDI  manages  a  list  of  channels.  The 
channel  will  be  created  and  a  number  assigned  for  accessing  it 

Example  11: 
int  my_chann«l; 

if  (gdi  op«n  channel  (my  dbConn,  Smy  channel)  U  GDI  SUCCESS) 

...  handle  error ... 

) 

Example  12  checks  to  see  if  the  channel  is  still  open. 

Example  12: 

if  (gdi  channel  is  open  (my  dbConn,  my.channei)  U  TRUE) 

{ 

...  handle  error ... 

} 

Example  13  shows  how  QtSJtu^O  discards  any  unprocessed  query  results.  For  ORACLE,  this 
cancels  a  query  after  the  desired  number  of  rows  have  been  fetched  and  frees  any  resources 
associated  with  the  cursor.  For  SYBASE,  it  cancels  any  rows  pending  in  the  DBPROCESS 
results  buffer  if  the  user  did  not  process  all  rows  in  the  results  set  For  POSTGRES,  this  dears 
the  portal,  if  appropriate. 

Example  13: 

If  (gdLflush  (my.dbConn,  my_channal)  l>  GDI  SUCCESS) 

{ 

...  handle  error ... 

} 

gdi_at)ortO  terminates  the  currently  executing  command.  For  ORACLE,  if  no  command  is  cur¬ 
rently  executing  and  the  next  command  is  a  fetch,  the  fetch  will  be  aborted.  For  SYBASE,  all 
commands  in  the  current  command  batch  are  cancelled.  This  command  has  no  effect  for  POST¬ 
GRES. 

Example  14  doses  the  query  channel  created  in  Example  11 . 

Example  14: 

H  (gdi  dota  ehannal  (my.dbConn,  my  channal)  I-  GDI  SUCCESS) 

{ 

...  handia  arror ... 

} 


Baseine:  21.1 


OOf 


QumyEmeuUon 


5.  Query  Execution 

gdUjsubm^O  executes  any  database  query.  The  basic  sequence  is: 

1 .  Connect  to  the  database  with  gdijopmO.  Queries  will  be  submitted  on  the  (ft>Conn  that  is 
returned. 

2.  Populate  a  null-terminated  string  writh  an  database  query.  For  users  accustomed  to  ORA¬ 
CLE.  the  query  should  not  have  a  terminating  semi-colon  (;). 

3.  Execute  the  query  with  pdLsubm^/ 

4.  Handle  any  return  results,  if  the  database  c^ery  is  a  SELECT  (ORACLE  and  SYBASE)  or 
RETRIEVE  (POSTGRES).  a  dbObj  wiU  contain  the  results.  The  dbObj  is  described  in 
Section?. 

5.  Free  the  return  results  structure. 

The  test  routine  tst_sid>fnlt.c  has  a  complete  example. 
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6.  Specialized  Database  Functions 

Table  6  summarizes  the  specialized  database  functions. 


’lU»le6.  Summary  of  Spedalizcd  Database  Functions 


Name 

Description 

Man  Page 

SampleCode 

gdi_g«t_oouiit*r 

Gtt  a  uniqua  kay  U. 

gdi_galjoounlar(3) 

tstjBat_oountar.c 

gdi_wh«t_is_obi«ct 

Raluma  what  an  obfact  ia  and 
who  owns  k. 

nonayal 

tst_whatis.c 

gdi_crMl*jabi« 

Ciaataa  a  datWbaaa  tabla  baaad 

ontedbObidafinMon. 

nonayat 

tst_cfaata.c 
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7.  Data  Management  (dbObJ) 

The  Database  Ot^ect  (dbOt^)  manages  data  and  is  created  whenever  a  database  query  is  exe¬ 
cuted.  An  application  can  aiso  create  a  dbObj  and  store  data  in  K,  then  use  it  to  create  and  popu¬ 
late  a  table  in  the  database.  Its  structure  Is  defined  in  the  Ubgdi.h  include  file  and  depicted  in 
Figure  8. 


I  Tiiple  Container  | 

Number  of  ti4}ies  in  the  tuple  container 
[~  Column  Definitions 

Number  of  columns  in  the  column  definitions, 
database  query:  i.e.,  'select  *  from  messages  where  msgid-4'' 
Number  of  rows  affected  by  query. 

Command  number  In  command  batch  (SYBASE  only) 

Are  there  more  rows  from  a  select  that  could  be  fetched? 
Exit  status  (QDLSUCCESS  or  GDLFAILURE) 


A  linked  list  of  dbOU’s  would  be  returned,  for  example, 
after  executing  a  Sybase  command  batch  containing 
more  than  one  query.  There  would  be  one  dbObj  for 
each  command  executed. 


RGURE  8.  dbObi  Stiuctuie 


The  dbObj  consists  of  4  basic  parts: 

•  Tuple  Container 

Stores  query  results  if  the  query  is  a  SELECT  (ORACLE  and  SYBASE)  or  RETRIEVE 
(POSTGRES),  or  data  to  be  inserted  into  the  database  if  the  query  is  an  INSERT 
(ORACLE  and  SYBASE)  or  APPEND  (POSTGRES). 

•  Column  Definidons 

Describes  each  field  in  the  rows  stored  in  the  tuple  container,  such  as  column  name, 
data  type  and  size. 
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•  Query  ^formation 

Several  variables  store  miscellaneous  ^formation  such  as  the  text  of  the  database 
query,  the  number  of  rows  affected,  and  whether  the  function  succeeded  or  failed. 

•  Tuple  Construdtor 

Controls  the  structure  or  format  of  the  data  in  the  tuple  container. 

A  dbObj  should  never  be  accessed  directly  because  the  specific  structure  will  likely  change. 
Instead,  the  macros  and  functions  summarized  in  Table  7  should  be  used.  The  sample  code  ref¬ 
erenced  in  the  table  is  in  L/SS/7C/libgendfa/test 


Tible?.  Summary  <^dbObj  Macros  and  Fimctioiis 


Name 

Deacriplion 

SampleCode 

dbObi  Creation 

gdi_obfjcrnto 

CrMtM  •  rMwdbObj  and  with  tha 
apadfiad  constructor 

tst_creale.c,  tst_dbobj.c,  tstjn- 
seitZc 

gdi_obLd«stR)y 

Fraas  a  dbObj,  daailocating  all  aNo- 
catadfialds. 

intaracl_submitc,  tst_oonstr.c, 
tstjBreate.c,  tst_dbobi.c,  tstjn- 
seit1.c,  tst_insert2.c,  tst_sub- 
mlLc,  tst_whatis.c 

Tuple  Container 

GDLOBJ_TUPLES 

Pointer  to  tha  tupla  oontainar 

GDLOBJ_NUM_TllPLES 

Numbar  of  tuplas  in  tha  tuple  con¬ 
tainer. 

intaract^submiLc.  tst.oonstr.c, 
tstjdbobj.c,  t8tjnsert2.c,  tst_- 
submitc 

Cokunn  DennMona 

GDLOBJ_COL_DEFS 

Pointer  to  an  array  of  column  defini¬ 
tions. 

GDLOBJ_NUM_COl.UMNS 

Number  of  columns. 

QueryStatua 

GDI_OBJ_QUERY 

Database  query. 

tstjnsert1.c 

GDLOBJ_ROWS_AFFECTED 

Number  of  io«vs  aflacted  by  the  data¬ 
base  command. 

t8t_dbobi.c,  tst_insert1  .c,  tstjn- 
seit2.c,  tst_submit.c 

GOLOBJ.CMD.NUM 

Command  number  (may  be  >1  for 
SYBASE) 

GOLOBJ.MORE.ROWS 

Indicates  there  were  more  rows  to 
be  had;  /.e.,  the  number  of 
records  requested  was  less  than 
the  actual  query  results. 

GDIjOBJ.STATUS 

Command  status 

Tuple  Constructor 
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7.1  Tuple  Contalnw 

Programs  do  rK>t  need  to  know  the  actual  structure  of  the  tuples  or  of  the  tuple  container.  The 
functions  summarized  in  Table  8  provide  data  access  regardless  of  the  actual  structure. 


IkbleS.  Summary  of  *nipleCootaiiicr  Macros  and  Functions 


SampieCode 


Name 

DesCf^idon 

gdijobLoontainarjcraat* 

CraatM  atupl*  oontainar  in  tha  dbObj. 

OdijotHjoontaiiMTjdMtioy 

Daatrays  a  tupta  oorttainar. 

gdLobLtupIsjcfsX* 

Craatasatupia. 

gdi_obLlvpl*-<l«sfoy 

Oaatroya  a  tupia. 

gdijobLtupl«_add 

Adda  a  tupla  to  a  tupia  oontainar. 

gdi_obLtupi«_r«trwv« 

Ratriavaa  a  tiipla  from  a  tupla  oontainar. 

gdi_obLfilLdai* 

Inaarta  data  into  atupia. 

gdi_ot^at_data 

Raada  data  from  atupia. 

mjdbobi.c,  tit_ins<rt2.c 


M_dbob|.c,  ttt_ins«rt2.c 


m_dbob(.c.  tft_ins«rt2.c 


M_oonstr.c,  tst_dbot^.c,  tst_in- 
SMt2.C 


m_oonstr.c.  M_dbobi.c, 
t*t  inMrt2.c 
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Like  the  dbObj.  the  dbColDef  should  not  be  accessed  directly.  Instsad  the  functions  and  macros 
listed  in  Table  9  should  be  used. 


’IUUe9.  Siuninary  of  dbColDef  Macros  and  FuiictkMis 


SampleCode 


Name 

Description 

gdi_ool_d«f_cnMt* 

CTMlM  a  naw  column  definition 

gdi_col_d«f_dMtroy 

daatroya  (daalocataa)  a  column  daA- 

^1^  — 

fiDcin* 

gdi_ooljd«Ladd 

Adds  a  column  definition  craalad  with 
gdi_eol_det_enat90^  >  dbObf. 

GOLOBJ_COL_NAME 

Qel  the  name  of  a  column  given  a  col¬ 
umn  number. 

GDI_OBJ_CX)L_CTYF»E 

Qel  the  C  type  of  a  column  given  a 
column  number. 

GOLOBJ.COL.PRECISiON 

Get  the  precision  of  a  column  g^en  a 
column  number. 

GDI_OBJ_COL_SC5ALE 

Get  the  scale  of  the  column  given  its 
column  number. 

GOLOBJ_OOL_L£N6TH 

Get  the  length  of  the  column. 

QDLOBJ_OOL_DBTYPE 

Gel  the  datdbaae  ddUi  type  tor  a  col¬ 
umn. 

GOLOBJ_CCX._DBTYPE_S 

Gat  the  database  string  for  aeating  or 
describing  a  column. 

GOI_OBJ_CXX._ALLOW_NULL 

Gat  the  ailow_nuR  flag. 

titjctMto.c,  tst_dtx)bi.c. 
M  ina«ft2x 


t«tjdbobj.c, 


M_dt>obj.e,  t*tJnMrt2.c 


tstjoonttr.c,  tst_dbobj.c, 
tst_insMt2x 


tst.dbot^x,  tstjm«it2.c 


tstjdbobi.c,  tstJnMrt2.c 


tst_dbob|x.  istjns«ft2.c 


ttLdbobj.c,  tttJnMtt2.c 


Mjdbobj.c.  t•tJnMrt^.c 


M_dbobi.c.  tstjns«it2.c 
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7^  Tupl«  Constructor 

The  tuple  constructor  is  specified  at  the  time  a  dbObj  is  created.  It  stores  pointers  to  the  routines 
that  are  actually  invoked  when  the  user  application  calis  subse<^ent  GDI  routines,  thus  hiding 
lower  level  data  structures. 

For  example,  when  an  application  calls  gdl^obUieLcIsaaO.  gdijdefj/etjdataO  is  actually 
invoked  if  the  dbOt^  was  created  with  QDi_DEFAULT,  and  gdlj8di_get_daiB()  is  invoked  if  the 
dbObj  was  created  with  GDLSDLCONSTR. 


Default  Constructor 


GDI  Routines 
gdjobLoontainer.destrDyO 
gdi_obLoontainer_create() 
gdi_obLtuple_add() 
gdi_obLtuple_retrieveO 
gdi_obLtuplO-<f^stroy() 
gdl.obLtuplejcreateO 
gd.obLfill-dataO 
gdi_obLgat_dataO 


S-PLUS  Constnictor 


FIGURE  10.  Tuple  Constructor 


BaseSne:  21.1 


QUUmrUmuml 


Etror  Handling 


8.  Error  Handling 

Errors  are  managed  on  a  connector  by  connector  basis,  each  dbConn  storing  information  for 
activity  on  its  channels.  The  status  of  a  function,  whether  it  succeeds  or  fails  (GDI_SUCCESS  or 
GDLFAILURE).  is  always  recorded  in  the  dbConn  along  with  the  specific  error  code  and  mes¬ 
sage  string.  The  dbConn  stores  information  about  the  last  command  executed,  overwriting  previ¬ 
ous  statuses.  For  that  reason,  the  dbObj  also  records  the  exit  status. 

Some  functions,  such  as  dbOt^  functions,  do  not  have  a  dbConn.  Also,  an  application  does  not 
have  a  dbConn  until  a  call  to  f^_opwtO  succeeds.  For  these  cases,  the  error  code  and  text  are 
stored  in  a  global  location  accessed  by  specifying  a  NULL  dbConn. 

Figure  11  depicts  how  an  error  that  may  have  occurred  inside  a  GDI  subroutine  gets  communi¬ 
cated  back  to  the  user. 


FIGURE  11.  GDI  Error  HandUng 

Two  sets  of  error  handling  functions,  one  for  the  user  and  one  for  the  lower>level  GDI  functions, 
provide  error  handling  capabilities  and  are  described  in  the  following  two  sections. 
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8.1  UMr  Error  Functions 

This  section  discusses  what  the  user  must  know  to  manage  errors,  including  how  to: 

•  Detect  if  a  GDI  function  failed. 

•  Retrieve  the  error  from  the  dbConn. 

•  Control  whether  datdhase  warnings  return  GDLSUCCESS  or  GDI_FAILURE. 

•  Detxjg  problems. 

A  user  detects  failure  by  checking  the  return  status  of  a  function.  Most  GDI  functions  return 
GDLSUCCESS  or  GDI_FAILURE.  Information  about  the  error  is  stored  in  the  dbConn  used  in 
the  function  call.  For  example: 

Example  IS: 

H  (gdi_commit  (my_dbConn,  channo)  I-  GDLSUCCESS) 

{ 

gdi_arrorjgat  (my_dbConn,  Sarrcoda,  arrtaxt.  maxtaxtian,  Sstatus,  Ssavarity); 
fprintf  (atdarr,  *%a\n*,  arrtaxt); 

} 

Functions  that  allocate  structures,  such  as  gdLopenO,  return  a  pointer  to  the  new  dbConn  struc¬ 
ture.  A  NULL  return  pointer  indicates  ^t  the  routine  has  failed.  The  following  gdi_open()  call 
demonstrates  both  how  to  check  for  a  NULL  return  and  how  to  retrieve  an  error  from  the  NULL 
dbConn: 

Example  16: 

If  ((my.dbConn  -  gdLopan  (vandor,  account,  password,  databasa,  sarvar,  appnama)) 

—  (dbConn  *)  NULL) 

{ 

gdLscrorjgat  ((dbConn  *)  NULL.  Sarrcoda.  arrtaxt,  maxtaxtian.  Sstatus.  Saavarity); 
fprintf  (stdarr,  '%a\n*,  arrtaxt); 

} 

Sometimes  a  database  generates  a  warning  which  may  or  may  not  be  important  to  an  applica¬ 
tion.  For  instance,  ORACLE  databases  set  a  warning  fi^  under  the  following  conditions: 

•  A  user  updates  or  deletes  a  table  without  a  where  clause. 

•  A  fetch  truncates  data  in  a  column. 

The  user  can  instruct  the  GDI  to  treat  such  wamlr^  as  total  by  setting  the  gdijenorJnitO  argu¬ 
ment.  threshold,  to  GDLWARNING.  The  ttweshokt  indicates  the  error  level  that  is  considered  a 
failure  and  which  cause  a  GDI  function  to  return  GDl.FAiLURE.  The  threshoUmay  be  changed 
at  any  time  and  the  current  setting  may  be  checked  with  a  call  to  g<M_errorJia^(). 

grfijsrrorJnltO  also  has  a  debug  flag.  When  set  to  GDLDEBUG.ON.  errors  are  automatically 
output  to  stderr.  When  set  to  GDI.DEBUG.VERBOSE.  addMonal  debug  messeges  are  automat- 
icaily  output  to  stderr.  These  options  are  especialiy  useful  during  the  early  stages  of  application 
development  but  should  not  be  used  as  a  r^>lacement  for  actual  error  handling. 
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Table  1 0  summarizes  user  error  handling  functions  and  macros. 

Table  10.  User  Error  Handling  Functioiis  and  Macros 


8.2  Low-Levol  Error  Functions 

The  low-level  routines,  summarized  in  Table  11,  store  errors  In  the  dbConn.  These  functions 
should  not  be  called  by  user  applications.  Developers  writing  GDI  functions  that  will  be  called  by 
user  applications  should  be  aware  of  these  functions. 


lUrlell.  Low-Level  Error  Setting  Functions 
Name  Descrip^n  Man  Page 


gdi_«rror_app  S«ls  anor  ooda  and  taxt  in  tha  dbConn. 

gdi_waminsLspp  SatsaGOlwamino.  KttwthraahoUissattohigharlhanGOI  - 
WARNING  or  if  tha  arrarN  coda  ia  GDI  NOERROR  than  tha 
dbConn  atatus  la  aat  to  GOLSUCCESS.  Othaiwiaa  tha  atatus  is 
sattoGDLFAILURE. 

gdi_srror_unix  Gats  artor  coda  from  Unix  anno  and  anor  taxt  from  ayaanortbrN 

a  UNIX  arror  occurrad  (for  axampia,  a  maKoofailad).  Storas  in 
dbConn  by  eating  gtPjmorjpf^). 

orajsqlcajBnor  ORACLE-apadfic  routina  that  storas  SQLCA  arror  information  in  ora_sqlca_orror(3) 
tha  dbObf.  For  uaa  by  PRO*C  routinas. 
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8^  Known  Probloms 
Asynchronous  Processing 

Since  errors  are  manaoed  at  the  dbConn  level,  channels  that  execute  commands  asynchro¬ 
nously  should  not  belong  to  the  same  dbConn  since  they  will  overwrite  each  other's  error  status. 
In  this  case,  additional  dbConn  structures  should  be  used. 

ORACLE 

ORACLE  is  signal-sensitive,  using  SIQINT  for  its  network  communications.  Special  ORACLE- 
provided  routines  must  be  used  to  put  alternate  SiGINT  handlers  in  place.  For  more  information, 
see  your  local  ORACLE  Database  Administrator. 

POSTGRES 

Be  aware  that  POSTGRES  error-handling  in  the  current  baseline  release  is  weak  and  is  being 
addressed  in  the  next  release. 
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9.  Transaction  Management 

A  transaction  is  a  group  of  database  statements  that  are  treated  as  a  singie  unit,  I.e.,  the  effects 
are  seen  in  their  entirety  or  not  at  ail.  if  queries  executed  inside  a  transaction  change  the  data¬ 
base,  those  changes  do  not  become  permanent  until  the  transaction  is  committed.  A  rollback 
negates  alt  changes. 

Each  database  manages  transactions  differently.  By  default,  each  POSTQRES  and  SYBASE 
statement  commits  as  soon  as  it  has  successfully  completed;  you  must  explicitly  begin  a  transac¬ 
tion  to  group  multiple  statements  together.  grMJoeginjranQ  starts  a  transaction  for  POSTGRES 
and  SYBASE  databases.  No  changes  will  become  pemnanent  until  a  g(S_commit()  is  executed. 
Ail  changes  within  the  uncommitted  transaction  may  be  undone  with  g(S_rollback(). 

By  default  ORACLE  implidtiy  starts  a  transaction  with  the  first  database  statement  No  changes 
become  permanent  until  a  gdi_commltO  is  executed,  and  all  uncommitted  changes  may  be 
undone  with  gdi_rollback().  gdl_auto_commltO  puts  ORACLE  into  a  mode  where  every  state¬ 
ment  commits  automatically  as  soon  as  it  competes. 

Two  conditions  may  automatically  cause  a  commit  depending  on  the  database: 

•  A  DDL  statement,  such  as  aeate  or  drop,  commits  pending  changes  even  if  the  state¬ 
ment  itself  tells. 

*  gdi_dose()  commits  pending  changes  before  tenninating  the  database  connection. 

In  general,  it  is  better  to  explicitly  commit  or  rollback  by  storing  the  proper  statement  in  a  query 
string  and  executing  it  with  g(S_submit()  or  by  using  one  of  the  functions  summarized  in  Table  1 2. 


Table  12.  IVaiisaction  Management  Functions 


Function 

Descrip^n 

Database 

gdi_b«gin_tran 

B«gin  a  multi-statamant  transactiofl 

POSTGRES,  SYBASE 

gdi_coflifnit 

End  a  transaction,  making  all  changes  parmanant. 

all 

gdLroUback 

End  a  transaction,  discarding  all  changes. 

all 

gdi_8av«point 

Set  a  savepoint 

ORACLE,  SYBASE 

gdi_auto_oom(nit 

Have  each  statement  automaticaliy  commit  if  it  s«Joceeds. 

ORACLE 
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10.  S-PLUS  Database  Interface 

The  S-PLUS  database  interface  lets  a  user  interactively  execute  a  database  query  at  the  S- 
PLUS  prompt,  then  transparently  transfers  database  query  results  into  S-PLUS  where  they  may 
be  manipulated  with  S-PLUS  functions.  The  databases  currently  supported  indude  Montage, 
Orade,  Postgres.  and  Sybase. 

To  use  it.  the  user  must  know: 

•  The  query  language  of  the  target  database:  SQL  for  Montage,  Orade  and  Sybase, 
POSTQUEL  for  Postgres. 

•  The  S  Language. 

•  How  to  use  the  following  functions  described  in  this  section: 

libsdi  Loads  the  S-PLUS  Database  Interface. 

s<S.open  Opens  a  connection  to  a  database. 
sa.submit  Executes  a  database  query. 

sctt.close  Closes  the  database  connection. 

10.1  Starting  S-PLUS 

Figure  12  shows  how  to  start  S-PLUS  and  load  the  database  interface  using  the  libsdi  command, 
which  creates  the  three  sd/ functions  (scB.open.  sdisubmit  and  sd/.c/ose)  that  are  used  for  man¬ 
aging  a  database  connection  and  queries. 


RGURE 12.  Loading  S-PLUS  Database  Interface 

Sites  may  be  configured  to  automatically  load  the  interface  for  a  given  database.  Figure  12  is 
from  a  site  that  uses  Orade  and  Montage;  Orade  is  set  to  the  default,  but  in  this  case  is  being 
overridden  with  the  libsdi(ynontag0")  command. 

On-line  help  is  available  by  entering  library(h0^libsdl). 
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10.2  Connecting  to  •  DatalMM 

sdl.openQ  establishes  a  connection  to  the  liatahase  and  takas  the  following  parameters; 


vendor 

Name  of  the  database  vendor  {montage,  orade.  postgres,  or  Sybase). 

account 

Database  account 

password 

Password  string. 

dataJoase 

Name  of  the  database. 

server 

Database  server  name. 

appname 

Name  of  the  application  (Sybase  only). 

Some,  or  even  all.  of  the  parameters  may  be  optional  depending  on  the  database.  Figure  13 
shows  a  user  connecting  to  the  node  Montage  database,  using  database  defaults  for  all  parame¬ 
ters  except  the  database  name. 


Baselne:  21.1 


10-2 


aUlMartlmuM  8-PLU8Dulatamimrtae» 


10^  Executing  DatabaM  QuariM 

s(M.submit()  executes  database  queries,  taking  the  following  parameters: 

query  String  containing  a  complete  database  query. 

maxrec  Maximum  number  of  records  to  fetch.  If  set  to  *1,  all  records  will  be 
returned.  If  set  to  0.  up  to  500  records  will  be  returned.  Otherwise  set  it  to 
the  maximum  number  of  records  you  want 

verbose  On  by  default  setting  it  to  0  will  suppress  status  messages. 

debug  Off  by  defeurlt,  allows  setting  several  debug  levels  to  help  troubleshoot  any 
problems  that  might  occur. 

Figure  1 5  builds  and  executes  a  database  query,  reque^ng  Just  the  first  50  rows,  it  then  lists  the 
query  result  attributes  and  row  count 


-  . - 

. . --*• - - 

'  ll” 

>  quary  <-  •■•laet  ■■  fcoa  Mctar" 

>  X  <-  sili.mlailttqiMxy,  50) 

■di.xulBilt:  quary  ooaplat^  atxxsa) 
>  attrilNitas(x) 

Bsfully;  50  rem(m)  I 

[1]  -lakay 

"ooa.daq.sq- 

*eEttisa_ld" 

*olM_yaaE*' 

[ 5 ]  "oba jaonth” 

"ofaa.day* 

"oba.tbaa" 

"data.typa" 

[9]  "luuqiio'’ 

"atEaaacjaauroa 

•  *uflaq" 

[13]  "loeatioo* 

•latltuda* 

"lonqituda" 

*U|>_data* 

•q_p«>8" 

[17]  -q_data_tiaa- 

”q_caooEd* 

"bul.tlM" 

[21]  -buljiaailac- 

"aouraa_id* 

"atEMBuldant* 

"qe.vaEBion" 

[25]  "data^vail* 
[29]  "nuajhiata" 

>  xltupla.oount 

Cl]  50 

>  1 

"tu^a.oount* 

"nsiiEfe* 

ncuRE  IS.  Executing  a  database  Query 


Entering  x  at  the  S-PLUS  prompt,  partially  shown  in  Figure  16.  outputs  the  data  loaded. 


>  X 
$ak«y: 

[1]  1300  1400  1500  1600  1700  ISOO  1900  2000  2100  2200  2300  2400  2500  2600  2700 
[161  2800  2900  3000  3100  3200  3300  3400  3500  3600  3700  3800  3900  4000  4100  4200 
[31]  4300  4400  4500  4600  4700  4800  4900  5000  5100  5200  5300  5400  5500  5600  5700 
[46]  5800  5900  6000  6100  6200 

$*ODil  datt 

[1]  ~6054  6056  7058  7060  9068  15099  15099  15099  15099  15099  16083  16083 
[13]  16083  16083  16089  16089  16089  16089  16089  16089  16M9  16093  16093  16093 
[25]  16093  16093  16093  16096  16096  16096  16096  17086  17086  17086  17086  17086 
[37]  17086  17086  21056  23056  23140  24056  24093  24093  24093  25089  25089  25089 
[49]  25089  25089 


nGURE  16.  Displaying  Data 
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Any  query  legal  for  the  target  database  may  be  executed.  Figure  1 7  executes  a  more  Interesfing 
query  Involving  a  join  query  that  selects  twro  Montage  array  types.  In  this  example,  it  selects  all 
available  results  (maxrec  « -1 ). 


rirrr 


>  qiMcy  <-  "Mlaot  m2.9totJPaKm  as  taap,  ■Z.DmiUL.^sss  as  dspth  froai  aastac  ■!, 
■sasursBMDts  m2  ulisrs  ml.MKsy  >  m2.IB(sy  -1  and  OootalBs(Ba«(PDt(10,  -175),  Pnt( 

20,-155)),  nl.Itooatioa)* 

>  X  <-  sdl.sufamlttquscy,  -1) 

sdi.sulsiit:  quacy  oaavlsiad  suoosssfully;  51  raw(s) 

>  attrUutss(x) 

[1]  "tamp"  "diptli"  *tupls. count" 

>■ 


RGURE 17.  Executing  a  JOIN  Query 

While  any  valid  query  may  be  executed,  it  is  irr^sortant  to  realize  that  the  GDI  passes  queries 
straight  through  to  the  target  database.  A  query  containing  the  Grade  outer  join  operator  will  fail 
if  sent  to  a  Sybase  database  and  vice  versus.  Likewise,  the  Contains  spatial  function  in  the  query 
in  Figure  17  is  spedfic  to  Montage  and  will  not  work  if  sent  to  Sybase  or  Grade. 
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Figure  20  and  Figure  21  plot  the  first  10  vectors. 


rirrr^ 


>  aouro 

>  plot  (xtUapKUl,  -1  ■  xldopthlll]),  xlih^TaniOKatiif,  ylab«'‘Doptli'*) 

>  par(Bfca»*e(3,5)) 

>  for  (i  In  (1:10))  (  plot  (xlt«np((l]],  -1  *  xSdoptlini]],  xlabs^Uap".  ylab«*d 
opth")  ) 

>  I  _ 


FIGURE  20.  Plotting  yuMple  ReeulM 


FIGURE  21.  S^US  Plot  (ftn  Vectors) 
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^OJS  Exiting  S-PLUS 


S(M.close()  disconnects  the  S-PLUS  session  from  the  database.  The  commarKts  in  Figure  22  dis¬ 
connect  from  the  database  and  exit  S-PLUS. 


mu.cIqmo 
datalMM  oloMd 

Rl" 


lU fully 


FIGURE  22.  ExUng  S-PLUS 

10.6  Transaction  Management 

Transaction  management  is  Implemented  slightly  differently  in  aii  the  databases  the  S-PLUS 
database  interface  supports.  The  most  notable  cfifference  is  between  Oracle  and  the  other  three 
databases  (Montage.  Postgres,  and  Sybase). 

The  first  Orade  statement  implicitly  starts  a  transaction,  which  is  not  ended  until  a  commit  or  mil- 
bad(  is  executed.  If  queries  executed  by  sdl.submltO  change  the  database,  those  changes  do  not 
become  permanent  until  a  com/ntf  occurs.  A  commitmakBS  all  changes  pennanent  as  does  any 
DDL  statement  such  as  create  or  drop.  A  roit)ack  undoes  all  changes.  sdidoseQ  commits  all 
pending  changes. 

A  transaction  in  Montage.  Postgres.  and  Sybase  must  be  expiicitty  started  using  the  conventions 
of  those  databases. 
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11.  FORTRAN  Interface 

The  QDI  FORTRAN  interface  provides  database  access  from  FORTRAN  77  s^ications.  To  use 
K,  the  user  must  know: 

•  The  query  ianguace  of  the  target  database. 

•  The  FORTRAN  77  Language. 

•  How  to  use  the  GOi  functions  and  subroutines  described  in  this  section. 

The  software  components  iisted  beiow  are  referenced  throughout  this  section.  Contact  your  iocal 
system  or  database  administrator  to  determine  the  actual  location  on  your  system: 

libraries  The  main  GOI  Ubrary  is  named  Hbg(Sju  Each  database  has  its  own  addi¬ 
tional  ltt)rary,  named  Ubg(^M  for  POSTGRES.  li)gcBora.a  for  ORACLE, 
and  ttigdis^a  for  SYBASE  Each  database  also  has  ns  own  link  file, 
named  pg_ibik.o  for  POSTGRES.  ora_Unk.o  for  ORACLE,  and  syb_Unk.o 
for  SYBASE. 

incbtde files  The  GDI  FORTRAN  include  file  is  named  gdl_f77.h  and  must  be  included 

in  all  FORTRAN  source  code  that  executes  GDI  calls.  It  establishes  a 
labelled  common  that  contains  standard  codes  for  data  types  and  error 
handling. 

sample  code  Sample  code  is  available  in  the  GDI  source  code  tree.  For  its  exact  loca¬ 
tion.  contact  your  iocal  system  or  database  administrator.  The  Makefiles  in 
this  directory  will  be  configured  correctly  for  your  installation. 


11.1  Document  Organization 


This  section  is  organized  as  follows: 


Section  11.2 
Section  11.3 
Section  11.4 
Section  11.5 
Section  11.6 
Section  11.7 
Section  11.8 


Summary  of  all  GDI  functions  and  subroutines 

Database  connection 

Query  execution 

Error  handling 

Complete  sample  program 

Problem  tracking 

Known  problems  and  resbictions 


11.2  Subroutine  and  Function  Calis 

This  section  summarizes  the  FORTRAN  function  and  subroutine  calls,  sorted  alph^retically  by 
name. 

The  data  type  of  each  argument  is  listed  in  the  right  hand  column.  Character  variables  are  of  an 
arbitrary  length. 
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Tiblcl4.  FORTRAN  Data  Types  and  Functioos 


Name 

Description 

Type 

HEADER  VwiablM 

These  header  variables  are  defined  in  gtMjDT.h. 

GDI  DATATYPES: 

GDI  INT2 

integer 

GDI  INT4 

integer 

GDI  REAL4 

integer 

GDI  REALS 

integer 

GDI  CHAR 

integer 

GDI  STRING 

intagv 

GDLUNDEFINED 

ERROR  HANDUNG  &  DEBUGGING: 

integer 

GDI  SUCCESS 

integer 

GDI  FAILURE 

integer 

GDI  NOMAP 

integer 

GDI  NOCONN 

integer 

GDI  DEBUG.OFF 

integer 

GDI  DEBUG.ON 

integer 

GDI_DEBUG_VERBOSE 

integer 

GOLAOO.MAP.FIELO 

INTEGER  FUNCTION  GDI  ADD  MAP.RELD  (DBCONN, 

MAP  ID.  DB  NAME.  PGM.NAME. 
DATAJTYPE.  STR^LEN.  ARRAY.LEN) 

PURPOSE:  Execute  a  database  Query. 

INPUT  ARGUMENTS. 

DBCONN  Database  connect  ID  (see  GDI.OPEN). 

integer 

MAPJD  Query  map  ID  (see  GDI_OPEN_MAP). 

integer 

DB.NAME  Name  Of  the  database  column  In  the 

retrleve/select  1st. 

char 

PGM  NAME  Name  Of  the  FORTRAN  variable. 

char 

DATA  TYPE  GDI  data  type  of  PGM.NAME. 

integer 

STR  LEN  TheiengthlfDATA.TYPEIsa 

GDLSTRING. 

integer 

ARRAY.LEN  If  DMA.TYPE  is  an  array,  the  number  of 
elements  in  the  array.  This  Mil  always  be 

0  for  ORACLE  and  SYBASE. 

integer 

RETURN:  GDI  SUCCESS  or  GDI  FAILURE. 

integer 
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Deacfiption 


INTEGER  FUNCTION  QOLCLOSE  (DBCONN) 


PURPOSE: 


DBCONN 

UPTURN: 


Close  the  specttied  database  connection. 


connect  ID  (see  GDLOPEN). 


GDI  CLOSE  MAP 


RETURN:  GOi.SUCCESS  or  GOLFAILURE. 


SUBROUTINE  GOI_CLOSE_MAP  (DBCONN.  MAPJD) 
PURPC^E:  Ends  definition  for  a  query  mapping. 


DBCONN  Datdbase  connect  ID  (see  GDI.OPEN). 

MAPJD  OuefymaplD(seeGDI_OPEN_MAP). 


GOLDESTROY.MAP  SUBROUTINE  GDLDESTROY.MAP  (DBCONN,  MAPJD) 
PURPOSE:  Destroys  mapping. 


DBCONN  Database  oonnact  ID  (see  GDI  OPEN). 
MAPJD  Query  mi«>  ID  (see  GDLOPEN.MAP). 


SUBROUTINE  GDI.ERROR.GET  (DBCONN,  ERRCODE, 
ERRTEXT,  MAXTEXT,  STATUS. 
SEVERITY) 


PURPOSE: 


DBCONN 

MAXTEXT 


ERRCODE 

ERRTEXT 

STATUS 

SEVERITY 


Retrieve  the  error  from  the  GDI  error 
hander. 


Database  connect  ID  (see  GDI.OPEN). 
Length  of  ERRTEXT  variable.  Database 
message  text  longer  than  tMs  will  be 
truncated. 


Error  code. 

Error  message. 

GDI  error  stahjs  (GDI_SUCCESS  or 
GDI.FAILURE). 

GDI  severity  level  (GDI  NOERROR, 
GDLWARNING.orGDI  FATAL). 


integer 

integer 


integer 

integer 


integer 

integer 


Integer 

integer 


integer 

char 

integer 

integer 
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TiU>lel4.  FORTRAN  Data  Types  and  Functions 


Name 

DeacripUon 

Type 

GOLERROR.MIT 

SUBROUTINE  QOI  ERROR.INIT  (DBCX)NN.  DEBUG. 

THRESHOLD.  RESERVED1, 
RESERVED2) 

PURPOSE:  InWalze  anor  handtaia  Haas. 

INPUT  ABQUIdEtnS^^ 

DBCONN 

Database  connect  ID  (see  GDI  OPEN). 

integer 

DEBUG 

Default  settino  is  QDI.DEBUG.OFF. 
qdi_DSUG_ON  causes  snor  messages 
lobeoulDuttD  iUrtofT 
ODI_DSUG_VERBOSE  may  cause 
addMonal  messages  to  be  (MAput. 

integer 

THRESHOLD 

ContfDls  how  severe  an  error  must  be  in 
order  to  cause  failure.  The  default  setting 
is  GDLWARNING.  which  means  that 
warning  and  fatal  errors  both  return 
GDI.FAILURE  to  the  caling  routine.  If  set 
to  GDLFATAL.  then  only  fatal  errors 
return  GDI  FAILURE;  warnings  return 
GDI_SUCCESS. 

integer 

RESERVED1 

Currently  not  used. 

integer 

RESERVED2 

Currently  not  used. 

integer 

GOUNtT 

INTEGER  FUNCTION  GDIJNIT  (APPNAME) 

PURPOSE:  Initialze  the  GDI. 

INPUT  ARGUMENTS: 

APPNAME: 

Program  name. 

char 

neruNN: 

GDLSUCCESS  or  GDLFAILURE 

integer 

GOLOPEN 

INTEGER  FUNCTION  GDI  OPEN  (VENDOR.  ACCOUNT. 

PASSWORD.  DATABASE,  SERVER. 
APPNAME) 

PURPOSE:  Ooen  a  oonnacUon  to  a  database. 

INPUIARQUMSNTS: 

VENDOR 

Database  vendor  name;  currently 
includes  oradeoT  pos^yes. 

char 

ACCOUNT 

Database  account  or  user  name. 

char 

PASSWORD 

Password  for  the  account. 

char 

DATABASE 

Database  name. 

char 

SERVER 

Server  name  (Sybase  &  Postgres  only). 

char 

APPNAME 

Program  name. 

char 

RETURN: 

Database  connection  ID.  GDI.NOCONN 
means  it  failed. 

integer 
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Table  14.  FORTRAN  Data  Types  and  Functions 


Naim 

DesGfiption 

Type 

GDLOPEN.MAP 

INTEGER  FUNCTION  GDLOPEN.MAP  (DBCONN) 

PURPOSE:  EsiafalistMS  the  relationshiD  between 

dat^se  quety  columns  and  FORTRAN 
variables. 

INPUT  ARGUMENTS-. 

DBCONN  Database  connect  ID  (see  GDLOPEN). 

integer 

RETURN:  Query  mao  id.  GDI  NOMAP  means  it 

ttfled. 

integer 

GOLSUBMIT 

INTEGER  FUNCTION  GDI  SUBMIT  (DBCONN.  MAP  ID, 
QUERY.  MAXRECS.  RETRIEVED. 
AFFECTED.  MORE.DATA) 

PURPOSE:  Execute  a  database  ouerv. 

INPUT  ARGUMENTS: 

DBCONN  Database  connect  ID  (see  GDI  OPEN). 

integer 

MAP.ID  Query  m^  ID  (see  GDI.OPEN.MAP). 

integer 

QUERY  Character  string  containing  a  complete 

database  query. 

char 

MAXRECS  Controls  how  many  instances  are 

retrieved.  Should  be  set  to  the  maximum 
number  of  records  that  can  fit  into  the 
FORTRAN  variable. 

OUTPUT  ARGUMENTS. 

integer 

RETRIEVED  Records  the  number  of  records  retrieved. 

integer 

AFFECTED  Records  the  number  of  records  affected 
by  the  query. 

integer 

MORE  DATA  If  the  data  available  is  greater  than 

MAXRECS.  MORE  DATA  will  be  set  to 
TRUE. 

logicaTA 

RETURN:  GDI  SUCCESS  or  GDI  FAILURE. 

iMeger 

GDLTRACE 

SUBROUTINE  GDI.TRACE  (DBCONN.  STATE.  FILENAME) 

PURPC^E:  Turns  database-soedfic  debug  on/olf. 

INPUT  ARGUMENTS. 

DBCONN  Database  connect  ID  (see  GDLOPEN). 

integer 

STATE  TRUE  turns  trace  on,  FALSE  turns  it  off. 

integer 

FILENAME  Output  filename  (SYBASE  only). 

char 
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11^  Connecting  to  a  Database 

This  section  describes  how  to  initiaiize  the  OOi  with  QDIJNITO,  connect  to  a  database  with 
GDLOPENQ  and  disconnect  from  a  database  with  GDI_CLOSE(). 

GDIJNITO  initiatizes  the  QDi  to  communicate  with  the  database(s)  to  which  a  program  will  con¬ 
nect.  GDI_OPEN()  establishes  a  connection  to  the  database.  GDLOPENQ  arguments  were 
described  in  detail  in  Section  11 .2.  But  since  not  all  databases  use  all  arguments.  Table  1 5  sum¬ 
marizes  which  databases  use  each  parameter. 


Table  15.  GDLOPENQ  PanaaMim 


Parameter 

ORACLE 

POSTGRES 

SYBASE 

vendor 

yes 

yes 

yes 

account 

yes 

no 

yes 

password 

optional 

no 

yes 

flatwhfflflv 

optional 

optional 

yes 

server 

no 

optional 

yes 

appname 

no 

no 

yes 

Some  GDLOPENQ  parameters  are  optional. 

For  ORACLE,  password  is  not  applicable  to  ops$  logins  (logins  tied  to  operating  system 
accounts).  Also  the  entire  account/password  connect  string  may  be  sent  in  via  the  account 
parameter. 

For  POSTGRES,  if  datatiase  is  not  set.  ttie  connection  will  be  set  from  the  PGDATABASE  envi¬ 
ronmental  variable.  If  server  is  not  set  it  will  be  set  from  the  PGHOST  environmental  variable. 

GDLOPENQ  returns  an  integer  database  connection  handle  that  is  used  by  other  GDI  calls;  its 
main  purpose  is  to  store  error  information,  if  it  is  equal  to  GDI_NOCONN,  it  means  that  the  con¬ 
nection  failed.  Example  17  initializes  the  GDI  and  establishes  a  connection  to  a  POSTGRES  data¬ 
base. 

Example  17: 

C  mmm  InHiaMz*  the  GDI  end  connect  to  POSTGRES  database  'demo' 

include  '../../inciude/gdi_f77.h 

character*30  VENDOR.  DBNAME.  DBHOST.  na 

integer  DBCONN.  STATUS 

C  M*  Initialize  program  variables  — 

VENDOR  -  'postgres' 

DBNAME  -  'demo' 

DBHOST  -  'heel.s2k.berheley.edu' 

NA-" 
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C  mmm  InKwIiz*  GDI 

STATUS  .  GOLINIT  (’tampi*’) 

C  ...  OPEN  DATABASE  CONNECTION  ... 

DBCONN  .  GOI.OPEN  (VENDOR.  NA.  NA.  DBNAME,  DBHOST,  NA) 

IF  (DBCONN  .EQ.  OOI.NOCONN)  THEN 

...  hmndh  •mr,  dmterUfd  In  Snetion  11. S... 

END  IF 

If  the  tiatatase  and  serverparametars  are  set  in  the  PQDATABASE  and  PGHOST  environmental 
variables,  all  parameters  to  GDI_OPEN().  except  for  vendor,  can  be  blank. 

QDI_CLOSE()  disconnects  an  application  from  the  database,  demonstrated  in  Example  1 8. 

Exannple  18: 

C  ...  Disconnact  from  tha  databasa  ... 

STATUS  .  GDLCLOSE  (DBCONN) 
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11.4  Exscutlng  Queries 

GDI  SUBMITQ  executes  a  datatiase  query  and  returns  QDLSUCCESS  if  the  query  succeeded 
and  GOLFAILURE  if  it  did  not. 

The  GOi  distinguishes  betereen  queries  that  return  data,  as  with  a  POSTQUEL  retrieve  or  a  SQL 
seiect,  and  queries  that  do  not  return  data.  First  we  wiii  look  at  queries  that  do  not  return  data 
results. 


11.4.1  Queries  that  Do  Not  Return  Data 
Example  1 9  creates  two  classes  in  a  POSTGRES  database.^ 
Example  19: 


character*  100  QUERY 

C  This  is  not  a  ratriava  so  sat  MAP_ID  and  MAXRECS  to  0. 

intagar  MAP_ID.O.  MAXRECS-0 

intagar  ROWS_RETRIEVED.  ROWS.AFFECTED,  MORE.DATA 

C  ..........  CREATE  ensiarra  CLASS  .......... 

QUERY,  'craata  ensiarra  (yaar.int4,  iulday.int4,  pracip.int4,'  // 

&  'tmax.float4,  ‘tmin.float4,  tmaan.float4)' 

STATUS.GDI  SUBMIT  (OBCONN,  MAPJD.  QUERY.  MAX.RECS, 

&  "  ROWS.RETRIEVED,  ROWS.AFFECTED,  MORE.DATA) 

C  ..........  CREATE  sst  CLASS  ......... 

QUERY,  'craata  sst  (iat.float4.  long.(loat4.  tima.fioatS,’  // 

&  tafflp.float4{6]' 

STATUS.GOI  SUBMIT  (DBCONN,  MAP.ID,  QUERY.  MAX.RECS, 

&  '  ROWS  RETRIEVED.  ROWS  AFFECTED.  MORE.DATA) 


GDI_SUBMIT()  executes  any  query.  Example  20  loads  data  into  cnsleira,  then  updates  one  of  its 
attributes. 

Example  20: 

QUERY,  'copy  ensiarra  from  /usr/data/cnsiarra.dat’ 

STATUS.GDLSUBMIT  (OBCONN,  MAPJD.  QUERY,  MAX.RECS) 

QUERY,  'rapiaca  ensiarra  (cnsiarra.pracip.  -9.99)  *  // 

&  'whara  cnsiarra.pracip.0’ 

STATUS.GOI  SUBMIT  (OBCONN.  MAP  ID.  QUERY.  MAX  RECS, 

&  ROWS.RETRIEVED.  ROWS.AFFECTED,  MORE.DATA) 

After  an  update,  RQWS.AFFECTED  should  report  the  number  of  rows  that  were  updated.  Cur¬ 
rently  this  does  not  work  for  POSTGRES  databases. 


1.  Example  queries  are  from  the  IrOmductory  Guide  to  POSTGRESby  Emela  C.  VHIaros-Bainto. 
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11.4^  OuerlM  That  Rttum  Data 
A  query  that  returns  data  from  the  database  has  tuvo  ^eps: 

1.  Map  each  column  in  the  quer/4  retrieve  list  to  a  FOFVTRAN  varfabie. 

2.  Execute  the  query  with  GO/.Sl/BM/ro. 

GDI_CREATE_MAPO,  demonstrated  in  Example  21.  aNocaiss  a  mapping  to  estabUsh  relation¬ 
ships  between  a  query  column  and  FORTRAN  vadabies.  it  returns  a  MAPJD,  which  is  used  in 
the  other  mapping  cans. 

Example  21: 

C  mmmmmmmmmmmm  CrCat*  S  qUCfy  mSpping  mmmmmmmmmmmmmm 

INTEGER  MAP  JO 

MAP  ID  -  GDI  OPEN  MAP  (DBCONN) 

IF  (MAPJD  .EQ.  GOLNOMAP)  THEN 

WRITE  (6.*)  *GOI  OPEN  MAP  falM.' 

END  IF 

GDI_M)D_MAPJFtELDO,  demonstrated  in  Example  22.  matches  a  database  result  column  to  a 
FORTRAN  variable.  Each  column  in  a  query  must  have  a  corresponding  mapped  FORTRAN 


variable. 

Example  22: 

C  mmmmmmmmmmm  Msp  DatabsM  Columns  tQ  FORTRAN  vsTiablat  «— 

REAL  LATITUDE(IOO).  TEMP(6.100) 


REAL*8  TIME(IOO) 

CHAR*80  OUERY 

OUERY  -  ’ratriav*  s.latituda,  s.tamp,  t.tima)  from  a  in  ast’ 

STATUS  -  GOLAOD.MAP.FIELD  (DBCONN.  MAP  ID.  ’latituda’, 

&  LATITUDE.  ODLREAL4.  0.  0) 

STATUS  .  GOLAOO.MAP  FIELD  (DBCONN.  MAP  ID,  ’tamp’. 

&  TEMP.  ODLREAL4.  0.  6) 

STATUS  .  GDI.AOO.MAP  FIELD  (DBCONN.  MAP  ID,  ’tima’, 

S  TIME.  GDI.REALS.  0.  0) 

Note  that  the  temp  attribute  in  Example  22  is  a  FK^QRES  arra^  attribute  containing  6  values. 
This  syntax  is  only  valid  tor  POSTGRES  databases.  Currently  array  support  is  limited  to  2  dimen¬ 
sional  arrays,  and  variables  must  be  declared  caretoiiy.  The  size  of  the  POSTGRES  array  must 
be  the  first  dimension,  as  in  TEMP(6, 100).  The  number  of  rows  is  the  second  dimension. 

GDI__CLOSE_MAP(),  demonstrated  in  Example  23,  ends  the  definition  for  a  mapping. 

Example  23: 

C  mmmmmmmmm  End  QUCfy  Mapping  mmmmmmmmmmmmmmmmm 

CALL  GDI.CLOSE.MAP  (MAPJD) 
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QDI_DESTr^Y_MAP(),  demonstrated  in  Example  24.  drops  the  mapping  relationship,  freeing 
all  local  memory  aUocated. 

Example  24: 

C  Drop  Quory  Mop 

CALL  QDLDESTROY.MAP  (OBCONN.  MAPJD) 

The  MAPJD  does  not  have  to  be  destroyed  sItM’  executing  a  query  It  may  be  reused  in  subse¬ 
quent  queries  so  long  as  the  number  of  columns  do  not  change  or  the  data  types  of  the  colunms 
do  not  change. 

Once  the  mapping  has  been  established,  the  query  may  be  executed  with  QDI_SUBMIT().  dem¬ 
onstrated  in  Examisle  25. 

Example  25: 

C  ■■MsaraaMMa  EXOCUtO  til*  OUOiy  BMaaMMaanaBaraM 

intogor  MAXRECS.  ROWS.RETRIEVED,  ROWS.AFFECTED,  MORE_DATA 

MAXRECS-  100 

STATUS-GDI  SUBMIT  (DBCONN.  MAPJD.  QUERY.  MAXRECS. 

S  ROWS.RETRIEVED.  ROWS.AFFECTED.  MORE.DATA) 

MAXRECS  indicatBS  the  maximum  number  of  instances  or  rows  of  data  that  should  be  returned. 
It  must  not  be  set  higher  than  the  array  lengths  of  the  FORTRAN  variables.  The  number  of  rows 
actually  retrieved  will  be  stored  in  ROWS  RETRIEVED.  If  more  data  are  available  than 
MAXRECS.  the  MORL  DATA  flag  will  be  set  to  TRUE. 
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FORTRAN  htartaea 


I'tJS  Handling  Errors 

Some  GDI  functions,  such  as  GDLOPBNQ  and  QDIJOPBN_MAPO  return  an  integer  handle  that 
should  be  greater  than  0  if  the  call  succeeded.  Ail  other  GDI  functions  return  GDLSUCCESS  or 
GDLFAILURE. 

GDI_ERROR_GET()  retrieves  specific  error  information.  Example  26  calls  GDI_ERROR_GET() 
after  detecting  an  error. 

Example  26: 

character*80  ERRTXT 

intagar  OBCONN.  DBERR.  SEVERITY 

DBCONN  -  GDI.OPEN  (VENDOR,  na.  na.  DBNAME,  na.  na) 

IF  (DBCONN  .EG.  GDI  NOCONN)  THEN 

CALL  GDLERROR  GET  (OBCONN.  DBERR.  ERRTXT,  80,  STATUS, 

S  SEVERITY) 

WRITE(0.  *)  ERRTXT 

. handia  anor . 

END  IF 

GDI_ERROR_INlT()  initializes  two  error  handling  flags,  debug  and  threshold,  debug  and  thresh¬ 
old  may  be  changed  at  any  time.  Example  27  sets  debug  to  GDLDEBUG_VERBOSE  and 
thresholdto  GDLWARNING. 

Example  27: 

c  mmm  Output  vatbosa  dabug  masaagaa  A  traat  warnings  as  fatal 

CALL  GDI.ERROR.INIT  (DBCONN.  GOLDEBUG.VERBOSE,  GDI.WARNING) 

GDI_TRACE()  turns  database  vendor-specific  tracing  on  and  off  and  may  be  called  at  any  time. 
Example  28  turns  trace  on. 

Example  28: 

c  Turn  databasa  tracing  on 

CALL  GDI.TRACE  (DBCONN,  TRUE.  FILENAME) 
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11.6  Sampl«  Programs 

This  section  indudes  compiete  sample  FORTRAN  programs.  Example  29  is  a  POSTQRES 
example. 

Example  29: 

C  SampI*  POSTQRES  program  —————— 


includa  ’../../includa/gdi_f77.h' 


C  dafina  local  variablas 

C  — — Connact  to  databaaa  ———————— 

CHARACTERMO  VENDOR,  DATABASE.  NA 
CHARACTER*  16  PRGNAM 

INTEGER  DBCONN 

C  mmmmmmmmmm  Erior  handling  variabias  — — — — — 

CHARACTER*80  ERRTXT 

INTEGER  MAXTXT,  STATUS.  SEVERITY.  ERRCDE 


C  Quary  variablas 

INTEGERS  MAPJD 

CUADAOTCD^OA  OIIFOV 

INTEGER  MAXRECS,  ROWS.RETRIEVED,  ROWS.AFFECTED 

INTEGER  ROWS.LEFT 

LOGICAL  MORE.DATA 

C  Output  \teriablss 


REAL'S  TIME(20) 

INTEGER  NSAMP(20) 

CHARACTER*16  STA(20) 

INTEGER  I 


VENDOR  -  'postgras' 

DATABSE  -  'gaodamo' 

PRGNAM  -  'gdi  177 _pg  tast’ 

MAXRECS  .  20 
MAXTXT  -  80 

C  Soma  GDI.OPEN  argumants  ara  Not  ApplicaMa  (NA)  to  POSTGRES 

NA." 

C  Initializa  tha  QDL.....................' 


STATUS.  GDI  INIT  (PRGNAM) 

IF  (STATUS  .NE.  GDI.SUCCESS)  THEN 

WRITE  (6,*)  ’GDIJNIT  Faiiad.  Program  axiting.’ 
GOTO  999 
END  IF 
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FORTRAN  ln»mtae» 


Open  a  connaelion  to  tha  databaaoj 


DBCONN  -  GDLOPEN  (VENDOR.  NA.  NA.  DATABASE,  NA.  PRGNAM) 
IF  (DBCONN  .EQ.  GDI  NOCONN)  THEN 

CALL  GDLERROR_GET  (DBCONN,  ERRCDE,  ERRTXT,  MAXTXT, 
STATUS.  SEVERITY) 

WRITE  (6.*)  ’GDLOPEN  Failed:  Error  Code  ’.  ERRCDE 
WRITE  (6.*)  ERRTXT 
GOTO  999 
END  IF 

Setting  GDLDEBUG.ON  prints  errors  to  the  screen. 

CALL  GDI  ERROR  INIT  (DBCONN.  ODI_DEBUG_ON,GDI_WARNING, 
RESERVEDI,  RESERVE02) 

QUERY  -  ’retrieve  (w.time,  w.nsamp,  w.sta)  from  w  in  wfdisc’ 


Create  query  mapping.- 


MAP  ID  -  GDI_OPEN_MAP  (DBCONN) 

IF  (MAPJD  .EQ.  GDLNOMAP)  THEN 
GOTO  999 
END  IF 

Map  each  attribute  being  retrieved  to  a  FORTRAN  variable.  -*■ 

STATUS  .  GDI  ADD.MAP.FIELD  (DBCONN.  MAP  ID. 

’time’,  TIME.  GDI_REAL8. 0,  0) 

IF  (STATUS  .NE.  GDI.SUCCESS)  THEN 
GOTO  999 
END  IF 

STATUS  .  GDI_ADD_MAP_FIELD  (DBCONN.  MAP  ID. 

’nsamp’,  NSAMP.  GDI  INT4.  0.  0) 

IF  (STATUS  .NE.  GDI.SUCCESS)  THEN 
GOTO  999 
END  IF 


STATUS  -  GDI  ADD  MAP  FIELD  (DBCONN.  MAPJD. 

’sta’,  STA,  GDI  STRING.  16.  0) 

IF  (STATUS  .NE.  GDI.SUCCESS)  THEN 
GOTO  999 
END  IF 

CALL  GDI.CLOSE.MAP(DBCONN.  MAPJD) 


Execute  the  query  < 


STATUS  .  GDI.SUBMIT(DBCONN.  MAP  ID.  QUERY.  MAXRECS, 
ROWS.RETRIEVED.  ROWS.AFFECTED,  MORE  DATA) 

IF  (STATUS  .NE.  GDI.SUCCESS)  THEN 
GOTO  999 
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c 


Print  out  rotriovod  data. 


WRITE  (6.*)  ROWS.AFFECTED,  ‘  rows  satisfiad  tha  quary.' 
WRITE  (6.*)  ROWS.RETRIEVED. '  rows  wars  ratriavad.' 

DO  10  I  .  1,  ROWS.RETRIEVED 

WRITE  (6.*)  STA(I),  TIME(I).  NSAMP(I) 

10  CONTINUE 

IF  (MORE.DATA)  THEN 

ROW8.LEFT  -  ROWS.AFFECTED  -  ROWS.RETRIEVED 
WRITE  (6,*)  ROWS.LEFT.  *  mora  rosrs  ara  availabla.’ 

ELSE 

WRITE  (6,*)  'No  mora  data  axtou  in  tha  databasa.’ 

END  IF 


mmmmmmmmmmmmmmmm  DaSUOy  qUafy  mapping,  mmm 

CALL  QDI.DESTROY.MAP  (DBCONN.  MAPJD) 


999  STATUS  .  GDI  CLOSE  (DBCONN) 
END 


When  run  on  a  database  containing  seismic  data,  output  iooks  tike  this: 

%  0di.f77j)0_tast 


63  rows  satisfiad  tha  quary. 

20  rows  wars  succassfuily  ratriavad  from  tha  databasa. 


BLA 

63671 0425.00000 

MOX 

636710766.05000 

MO 

636710786.05000 

MO 

636710786.05000 

WRA 

636710849.49200 

WRA 

636710849.49200 

ASAR 

636710887.89900 

ASAR 

636710887.89900 

ARAO 

636711023.70900 

ARAO 

636711023.70900 

LTX 

636711827.00000 

GRF 

636713180.00000 

GRF 

636713559.00000 

KBA 

636713564.00200 

ASAR 

636713609.66400 

ASAR 

636713609.66400 

NRAO 

636713630.60300 

NRAO 

636713630.60300 

GRF 

636713920.00000 

GAR 

636713921.69900 

43  mora  rows  ara  availabla. 


14280 

1160 

1160 

1160 

2400 

2400 

2400 

2400 

4797 

4800 

10320 

2400 

2400 

12000 

2400 

2400 

4792 

4800 

2400 

2400 


11.7  Troubleshooting  Tips 

Here  are  a  few  tips  for  when  things  do  not  work  as  expected: 
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•  Test  database  queries  interactively  before  putting  them  Into  a  program. 

•  GOLERROR.INIT  with  the  debug  flag  set  to  GOI_DEBUQ_ON  outputs  errors  to  the 
screen. 

•  QDLERRORJNIT  with  the  debug  fl^  set  to  GDI.DEBUG.VERBOSE  outputs 
debug  messages  to  the  screen. 

•  GDLTRACE  set  to  TRUE  outputs  database-specific  debugging  messages. 

11.8  Current  Restrictions 

POSTGRES 

•  GDLSUBMITO 

ROWS.AFFECTED  will  not  be  set  unless  the  command  was  an  APPEND. 

Bulit-in  Types 

The  following  built-in  types  are  not  directly  supported  yet.  The  GDI  will  return  these 
types  as  strings  to  the  application. 

large  ot^ects 

types  composed  of  a  structure,  such  as  box  and  polygon 

•  User-Defined  Types 

The  following  SEQUIOA  types  are  handled: 

char2 

char4 

chars 

Adding  new  types  requires  changing  source  code  and  recompiling.  WP  are  working 
on  a  strategy  to  dynamically  manage  types. 

•  Database  Nulis 

If  a  database  attribute  is  NULL  (/.e.,  it  does  not  have  a  value),  the  output  variable  will 
be  assigned  a  value  as  follows: 

GDIJNT2.  GDIJNT4:  0 

GDLREAL4.  GDI.REALS:  0.0 

GDI.STRING:  blank  padded  to  the  size  of  the  FORTRAN 

variable 

GDI.CHAR:  blank 

•  Nanwd  Columns 

The  GDI  cannot  detennine  the  type  of  some  named  columns. 

Instead  of  this:  retrieve  (my_namei4).name)  from  p  in  foo 

Do  this:  rBtrieve(p.name)  from  p  in  foo 


BaseBne:  21.1 


11-15 


ODI_GEN_ASTRUCTS  ( 1 ) 


USER  COMMANDS 


GDI_GEN_ASTRUCTS  ( 1 ) 


NAME 

gdt ,jgea_Asinicts  -  tool  to  genenie  header  files  coniainmg  stnictnre 
declantioiis  for  the  GDI’s  Air^Stnictt  constructor. 

SYNOPSIS 

|di_fCB_Aatracls  parsgdi jgcB_AstnKts.par 
PAR  PARAMETERS 

aocowit  datahate  accouat/jpasswand  and  coonect  string  if  lequiied 
vendor  database  vendor  name 

qaery  syntactically  conect  sql  stasement,  NO  where  clause 
stmrtname  name  of  the  structure  to  be  geneiMed,  first  letter  CMwtalired  by  convention 
DESCRIPTION 

Hiis  tool  creates  data  structures  based  on  the  columns  resulting  fiom  a  database  query  and  ouqtutt  them 
to  a  header  file.  The  structures  usually  oorrespood  k>  a  table  structure  but  could  be  a  sub  or  stqteraet  of 
any  comlunatian  of  relatiaos.  Queries  are  submitted  with  gdi_submitO*  The  ArmyStructs  constructor 
and  the  header  generated  by  gdijgen_Astmcts  emulate  UbdbSirstyle  anr^  fetches  in  that  the  nqdes  are 
returned  in  an  array  of  strucoires.  See  gdi_submitO  for  a  complete  de^ption  of  how  to  fetch  data 
with  the  GDI. 

One  of  the  data  strucuires  contains  "NA"  values  for  each  attribute  or  column.  These  values  are 
obtained  fiom  the  database  table  najMdm.  The  na_value  thUe  has  2  fields,  attribute  and  na_value. 
Both  are  of  type  cliar(30).  The  not  availaUe  value  for  a  qpecific  attribute  can  be  stored  in  this  table. 
If  the  attribute  does  not  exists  in  M_va/iie  or  die  table  dore  not  exist,  default  values  are  used.  The 
default  for  inis  and  floats  are  -1  and  *^.0.  The  default  for  a  string  is  a 

The  select  list  of  queries  using  the  generated  header  file  nuist  correapond  to  that  of  the  query  used  to 
create  the  structures.  Every  column  in  the  query  must  have  a  column  of  the  same  name  arid  type  in  the 
header  file.  The  columns  in  the  select  list  may  be  a  subset  of  the  original  list  and  may  appear  in  any 
order. 

The  header  files  may  be  used  in  conjuncdon  with  gdijBdd_AnBySiructsO  and  gdi _get_AiTayStructsO. 
These  functions  provide  a  layer  around  gdi_submitO.  gdi^insertO.  and  the  dbObj. 
gdi _^_AiiaySttucisO  submits  the  query  and  retrieves  foe  array  of  uqilM  from  the  dbObj.  The  dbObj 
is  freed  by  the  function  and  the  array  of  tiqdes  is  returned  to  foe  calling  applicatioa  It  is  the  responsi¬ 
bility  of  foe  qtfdication  to  free  foe  results.  ^jBdd_AriaySlructsO  lakes  an  array  of  uqiles  and  inserts 
them  into  a  database  table.  The  dbObj  required  by  gdi_inxitO  is  created  by  the  function  and  destroyed 
before  the  function  returos.  See  M_AiTay^ro^_aabmit  and  tst_ArrayStiiicts_iiisert  in 
Ubgendb/lest  for  usage. 

The  sample  /NujUe  below  srould  generate  arrival^AstructsJi: 

aocount«''teaItimc/realiime@L'tPcdl:dev6033'' 

vendorWocacle" 

queryB''SELECT  *  from  aonval” 
stractnameB"  Arrival" 


DUGNOSnCS 

GDI_SUCCESS 

No  problem  generating  the  header  file. 

GDI_FAILURE 

An  error  occurred. 

FILE 

gdi jgen_Arn^Structsx 
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NOTES 

Not  iiiq)lemenied  for  FORTRAN. 

SEE  ALSO 

|di_iMMK3).  |di_nbMit(3).  |di_add_AiTayStnMti(3).  fdi j|et_AiTa7StnMt8(3).  UbdbSO: 

anra7_rct(^) 

AUTHOR 

Mari  Mottell,  SAIC  Geophysical  Syttems  Opentioo  Novenriter  1991 
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GDI_ABC»T(3) 


NAME 

g(ii_abort  -  aixKt  the  cunent  command 

SYNOPSIS 

SiKiwk  UbidLh” 

faU 

fdi_abort  (con) 

dbCon  *coaB:  /•  (i)  connection  */ 

DESCRIPnON 

gdijdnrtO  cvoels  fiU  qiwy  activity  on  a  given  dbComi;  honver.  behavior  inay  be  vendor  dqModem. 
For  (XIACLE,  if  no  command  is  cunently  executing  wA  the  next  louiine  is  a  fetch,  the  fetch  will  be 
asynchronously  aborted.  For  SYBASE  and  MONTAGE,  commands  on  aU  query  channels  assocuued 
with  the  dbOmn  will  be  cancelled.  gdi_aobrtO  has  no  effect  for  POSTGRES. 

ARGUMENTS 

con  The  <*«****■•*  connector  for  the  connection  which  the  channel  was  opened  on. 

DIAGNOSTICS 

gdi_aboctO  letuins  one  of  the  ftdlowing  sta&is  values: 

GDI^SUCCESS 

Abort  succeeded. 

GDI^FAILURE 

Abort  failed:  possibly  the  database  connection  dropped. 

FILE 

gdi_abarLc 

SEE  ALSO 

idi_laah(3) 

AUTHOR 

Jean  T.  Anderson,  SAIC  Geophysical  Systems  Operation,  Open  Systems  Division 
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NAME 

gdi_add_AiTayStnicts  -  Insen  an  airay  of  stnictiiits  into  a  tabk. 

SYNOPSIS 

fiMliide  "HbgdU" 
fiadiide  "<typo_AatnictsJi'' 

iat 


gdi_add_ArrayStnicls  (conn,  table  na 

aie,  array,  atapk, 

(ttiCona 

*corai; 

/*  0)  datahasr  connection  */ 

char 

*tablc_aaaM: 

/*  0)  datahasr  table  *f 

void 

•array; 

h  G)  may  ttf  structs  *! 

iat 

atuplc; 

/«  0)  number  of  tiqdes  in  the  array  */ 

ArrayStractsArgs 

•type; 

h  G)  structure  definition  •/ 

DESCRIPTION 

gdi_add_AfiayStnictsO  inseits  the  data  in  an  array  of  atrociares  into  a  taUe.  Headers  contain¬ 
ing  a  structure  definition  with  fields  corresponding  to  the  of  the  udde  are  created  with 

gdi _gea_Astrticts(l).  Although  the  structure  may  only  contain  fields  that  coneqxmd  to  cohnnns  in  the 
datahnsf.  taUe,  the  order  the  fields  in  the  structure  need  not  match  the  order  of  the  columns  in  the 
taUe. 

ARGUMENTS 

conn  The  database  connector. 

table^naaM  The  database  table  into  which  the  data  is  to  be  inserted. 

array  The  array  of  stnictures  containing  the  data  to  be  inserted  into  the  database. 

ntnpic  The  number  of  tuples  in  the  array. 

type  A  description  oi  the  anay  structure,  the  "NA"  values  and  other  infonnation  needed  to 

process  the  array  for  input  The  description  is  contained  in  the  ''<type>_Astructs.h'' 
header. 


EXAMPLE 

The  following  example  uses  a  header  dunqted  by  gdi _gea_Astructs(l)  using  the  query,  "select  *  from 
arrival".  The  structure  definitioo  in  atrival_AstructsJi  is  shown  below. 

typedef  struct  arrival  { 

char  sta  fT]; 

double  time; 

long  arid; 

long  jdaie; 

long  stassid; 

long  chanid; 

char  chan  (91; 

char  iphaae  (9]; 

char  stype  (2J; 

double  dehim; 

double  azimuth; 

dodUe  delaz; 

double  slow; 

double  delslo; 

double  etna; 

double  rect; 

double  amp; 
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double 

per. 

double 

iQgat; 

char 

CI9  [2]; 

char 

fm  [31; 

double 

anr; 

char 

<|ual[2); 

char 

auth  [16]; 

long 

commid; 

char 

IddalB  [18]; 

)  Arrival: 

The  f(dlowing  code  s^ment  inserts  data  into  the  database. 


iinclude  "libgdLh" 
ftnchide  "arrival^AstnictsJi'' 


dbConn  *00110: 

char  •taUe  « "arrival"; 

Arrival  *tiiples; 

int  ntiq)les  •  10; 


/*  database  connector  */ 

/*  array  of  tuples  */ 

/•  nunto  of  tuples  in  the  array  •/ 


int  etr^code;  /*  error  handling  variables  */ 

char  enr^text  [200]; 

dbStaois  status; 

dbEirLev  severity; 


...  initialize  the  GDI.  open  a  database  connection  ... 

...  create  an  array  of  nqdes  ... 

if  ((nbqiles  >  gdi  add  AnayStnictt  (conn,  table,  (void  *)  tuples,  ntigdes. 

&ARRIVAL_(XmTAINER_raF))  <  0) 


( 


gdijerror jget  (conn.  Aerrjcode.  err^iext,  sizettf  (entext). 
ifrftaiiw,  ^severity); 

...  handle  the  error ... 


DUGNOSnCS 

gdi_add_AiTByStructsO  returns  the  onmber  of  tqtles  inserted  if  successful,  otherwise  it  returns  -1. 
codM  and  messages  may  be  retrieved  fiom  the  database  cotmector  with  gtf_error_get(3). 

FILE 

gdi_AnayStructsx.  gdi_ArrivStructsJi 
SEE  ALSO 

gdi_ciTor_get(3).  ^ _gcn_Aatmcts(l).  gdi _fet_ArrayStmcls(3) 

AUTHOR 

B.  Madlitchie.  SAIC  Geophysical  Systems  Operatioo.  Open  Systems  Division 


Error 


Son  Release  4.1 


Last  change:  12/21^3  (v202) 
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GDI_AUTO_CX)MMIT(3) 


C  LIBRARY  FUNCTIONS 


GDl^AUrOJCOMMTT  (  3 ) 


NAME 

gdi_auto_ooiiunit  -  EnaUe  or  disidde  aitto  commit  mode 

SYNOPSIS 

«iKiwk ’BbgdUi'' 

tait 

t^juttojeommk  (coma,  mode) 

dbCoBB  *coui:  /•  (i)  dattfiir  connociion  */ 

iat  mode;  /*  (i)  auto  commit  mode.  TRUE  or  FALSE  */ 

DESCRIPTION 

A  datalwae  tcansaction  is  a  statement,  or  WMemmts,  mated  as  an  tnmif  mit.  if  aioo  mniipit  is 
enabled,  each  database,  statement  is  treaied  as  a  tnwsaction  and  the  lesnlts  are  antomadcaOy  cwnmiwfd 
when  die  statement  is  executed.  The  auto  commit  mode  is  oontroOed  at  the  connector  level  (rather  than 
the  channel  level). 

Note  that  the  ability  to  enable  or  disable  the  auto  commit  mode  is  only  inqtleinented  for  C^ACLE  con* 
nectkms.  The  auto  commit  default  mode  for  (XIACLE  connections  is  OPF.  SYBASE  always  grnnmits 
the  results  of  each  statement  at  executkm  time  (essentially  auio  commit  is  ON)  wniftas  gdi_bqiin  tran(3) 
has  been  called. 

The  state  of  die  auto  commit  mode  for  a  conneciioo  may  be  ascenained  through  the 
GDI_AUTOCOM_(Xf(oooo)  macro. 

ARGUMENTS 

conn  The  database  connector. 

■ode  Ibe  auto  commit  mode  to  be  set  IRUE  enables  auto  commit.  FALSE  disables  auto 
commit 

DIAGNOSTICS 

gdijuito_oommitO  returns  one  of  the  following  status  values: 

GDI_SUCCESS 

Operation  succeeded. 

GDI_FAILURE 

Opetatkm  failed;  possfoly  die  connection  dropped. 

PILE 

gdi^tranx 
SEE  ALSO 

gdijicginjran(3).  gdi_coaiaiit(3).  ■ili_roBbacfc(3).  ■di_aavcpoiat(3) 

AUTHOR 

B.  MacRitchie,  SAIC  Geophysical  Systems  Operation,  Open  Systems  Division 
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Last  change:  12/27/93  (v20.2) 


Sun  Release  4.1 


GDI_BEGIN_TRAN(3)  C  LIBRARY  FUNCTKX4S  GDI_BBGIN_TRAN(3) 


NAME 

gdi_begiii jm  -  Exiriickly  b^io  a  nansaction 

SYNOPSIS 

SiMlMk  HbadU" 

iat 

fdi_b^ia_tran  (oou,  chaaao,  traBi_MMc) 


dhConn 

*conB; 

h  (i)  datahase  connection  •/ 

tart 

channo; 

h  (i)  channel  immber  •/ 

char 

*traa_Bamc; 

/*  (i)  transaction  name  */ 

DESCRIPnON 

A  database  ttansaction  is  a  snawnnit.  or  statements,  treated  as  an  atomic  miL  gdijbegin juanQ  ejqili- 
dtly  begins  a  transaction.  Tbe  transartion  is  ended  by  a  gdijcommitO  or  gdijoQba^.  A «»— 
acquires  locks  on  data  as  it  queries  or  updates  the  datahasr.  Tire  locks  acquoad  during  a  ttansaction  are 
released  at  the  next  commit  or  roUbaclL  Transactioos  should  be  as  tight  and  smaD  as  possible  so  lock 
resources  needed  by  other  database  processes  are  released  badt  to  the  system. 

Transaction  management  is  impletnenied  slightly  differently  in  all  the  the  gdi  stqjports. 

gdi_b^in_ttanO  currently  has  no  affect  on  (BIACLE  datalnses  since  the  first  CXtACLE  statement 
implicitly  starts  a  transaction,  which  is  not  ended  until  a  gdijcommitO  or  gdijntilbadcO  occurs. 

ARGUMENTS 

conn  Tire  database  connector. 

chanuo  The  channel  number  (SYBASE  and  M^TTAGE).  SYBASE  transactions  are  handled  at 
the  DBPROCESS  level  MCB4TAGE  transactions  are  handled  at  the  connection 

level  but  each  gdi  query  channel  maps  to  a  separate  database  cotmection.  The  channel 
argumern  is  ignored  for  ORACLE  and  POSTGRES. 

tran^namc  Transaction  name  of  the  transaction  to  be  started.  This  argument  is  only  valid  for 
SYBASE  which  allows  nested,  named  transactions. 

DUGNOSneS 

gdi_b^in_tianO  returns  one  of  the  following  stanis  values: 

GDI_SUCCESS 

Operation  succeeded. 

GDI_^FAILURE 

Operation  failed;  possibly  the  counectioo  dropped. 

FILE 

gdi_tianx 

NOTES 

Not  implemenied  in  INGRES  yet 
SEE  ALSO 

idi_connait(3).  gdi_fet_dboption(3).  |di_rollhacl^).  gdljnivcpuiatCS).  idi_aet_dboption(3) 
AUTHOR 

B.  MacRitchie,  SAIC  Geophysical  Systems  Operation,  Open  Systems  Division 


Sun  Release  4.1 


Last  change:  12/27/93  (v202) 
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GDI_CHANNEL_IS_OPEN  ( 3  ) 


C  LIBRARY  FUNCnOKS 


GDI_CHANNEL_IS_Oi»EN  (  3  ) 


NAME 

gdi_ciiaiiiieIJs_open  -  b  channel  open? 

SYNOPSIS 

MHtedc  "HbsdLh" 

int 

|di_opcn_chanMl  (conn,  chauo) 

dbCou  *conB;  h  (i)  databatf  comection  •/ 

int  chaano;  /•  0)  channel  number  •/ 

DESCRIPTION 

gdijchannel_is_apen0  leiuras  TRUE  if  a  given  chaimel  is  open,  or  FALSE  if  it  is  not 
ARGUMENTS 

conn  Hie  datahaar  connector  for  the  connecrion  the  channel  was  opened  on. 

channo  Qiannel  number  cS  the  channel  to  be  checked. 

DIAGNOSTICS 

gdijchannetjsjopenO  reums  one  of  the  following  status  values: 

TRUE  Channel  is  open. 

FALSE  Channel  is  not  open. 

FILE 

gdi^channelx 
SEE  ALSO 

gdi_close_chaaad(3),  gdi_o|Mn_chaaacl<3) 

AUTHOR 

B.  MacRitchie.  SAIC  Geophysical  Systems  Operatioo,  Open  Systems  Diviskm 
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Last  change:  12/27/93  (v20.2) 


Sun  Release  4.1 


GOI_CLOSE(3) 


C  LIBRARY  FlINCIK^ 


GDI_CL0SE(3) 


NAME 

fdi_ckMe  -  close  the  specified  dattfwsr  connection 

SYNOPSIS 

ihMliide  "MbfdLh" 

int 

fdijehMe  (cou) 

dbCou  *com:  /*  (i)  datibnse  connection  */ 

DESCRIPTION 

gdijcloaeO  closes  a  speciBc  connection  to  the  dat^sr  and  fieet  the  dbComt  structure. 
ARGUMENTS 

conn  The  database  connector  for  the  connection  to  be  dosed. 

DIAGNOSTICS 

gdi_closeO  returns  one  of  the  fdlowing  status  values: 

GDI_SUCCESS 

Connection  successfully  closed. 

GDI_FAILURE 

Not  connected  to  database. 

FILE 

gdi_connx 
SEE  ALSO 

fdi_^opcn(3).  gdi_dead(3).  |di_edt(3) 

AUTHOR 

B.  MacRitchie,  SAIC  Geophysical  Systems  Operatioo,  Open  Systems  Division 


Sun  Release  4.1 


Last  change:  12/21193  (V2D2) 
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ODI_CLOSE_CHANNEL  (  3  ) 


C  LIBRARY  FUNCnONS 


GDI_CLOSE_CHANNEL  ( 3 ) 


NAME 

gdi_cloae_ciiaiinel  -  clote  a  datahaar  ctaaond 

SYNOPSIS 

fiacMe 'HbgdLh" 

iat 

|dijcloac_chaucl  (coui.  chauo) 

dbCou  /•  (i)  dartbaae  connecunn  */ 

iat  chaaao;  h  0)  cbaDoel  aianber  */ 


DESCRIPTKm 

gdi_clo8e_channel0  closes  a  specified  channel. 

ARGUMENTS 

coaa  The  connector  for  the  comectkn  the  cfaannd  was  opMed  on. 

chaaao  Channel  number  of  the  channel  to  be  closed. 


DIAGNOSTICS 

gdi_clooe_channelO  letums  one  of  the  following  status  values: 

GDI^SUCCESS 

Succeeded  in  closing  channel. 

GDI_FAILURE 

Could  not  close  channel,  possibly  because  the  connectioo  dropped. 


FILE 

gdi_channelx 
SEE  ALSO 

gdi_chaaacl_is_^opca(3),  gdlj>pen_^rhanafi(3) 

AUTHOR 

B.  MacRitchie.  SAIC  Geophysical  Systems  Operatioo,  Open  Systems  Diviskm 
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Last  change:  12/27/93  (v20.2) 


Sun  Release  4.1 


GDI_COMMlT(3)  C  LIBRARY  FUNCHONS  GDI_COMMIT(3) 


NAME 

gdi_caiiiiiiit  -  commit  cuncnt  tmnmction 

SYNOPSIS 

ftaicliide  "MbfdLh" 

bit 

fdijcommit  (cou,  ftoiao,  tnm_iamc) 
dbCou  *€au;  /•  (i)  dattimt  connectkin  */ 

iat  ckasBo;  /•  0)  chmiiiel  immher  •/ 

char  *traB_Bamc;  /*  (i)  transactioa  name  */ 

DESCRlPnON 

A  daiabaae  nansactiaa  is  a  statement,  or  stattments,  tremed  as  an  atomic  nnU.  gdijcommitO  ends  the 
cmient  tmnsactioo  by  afiplyiQg  all  dianges  to  die  database 

ARGUMENTS 

COBB  The  datahnar  connector. 

channo  The  channel  number  (SYBASE  and  MCMTAGE).  SYBASE  transactions  are  bandied  at 
the  DBFROCESS  lev^  MC^fTAGE  transactions  are  handled  at  the  Hatahiw-  connection 
level,  but  eadi  gdi  query  channel  maps  lo  a  separate  database  connection.  The  channel 
argumem  is  ignored  for  ORAQLE  and  POSTGRES. 

traB_Bame  Transaction  name  of  the  tnnaactioo  to  be  committed  This  argument  is  only  valid  for 
SYBASE  which  allows  nested,  mmed  transactions. 

DIAGNOSTICS 

gdi_commitO  returns  one  of  the  following  status  values: 

GOI_SUCCESS 

Commit  succeeded. 

GDI_FAILURE 

Commit  failed;  possibly  the  connection  dropped. 

FILE 

gdi_tnnx 
SEE  ALSO 

idijrollliack(3).  fdi_savcpoiBt(3) 

AUTHOR 

B.  MacRitchie,  SAIC  Geophysical  Systems  Operatioo,  Open  Systems  Division 


Sun  Release  4.1 


Last  change;  12/27/93  (v20.2) 


11 


GDI_I«AD(3) 


C  LIBRARY  FUNCTKX4S 


GDI.KADO) 


NAME 

gdi_dead  -  detennines  if  a  daiabaae  conneciion  is  dead  or  live 

SYNOPSIS 

MKhidc  "HbfdLh' 

iat 

•di  jdcad  (cou,  chasBo) 

dbCoBB  *caa«;  /*  0)  datdbair  connectioii  •/ 

fait  •chaaao;  h  0)  databaar  channel  number  *! 

DESCRIPTION 

gdi_deadO  pugs  die  to  deiennine  if  a  databaar.  cannec  tinn  is  sdll  established. 

ARGUMENTS 

CmUl  Tli»  HatntwKM.  remnre*rr  far  tvwvirtiflw  In  Ivt  teUwd 

channo  The  channel  number  for  the  channel  to  be  tested. 

DIAGNOSTICS 

gdijdeadO  returns  one  of  the  foUowiiig  status  values. 

GDI_SUCCESS 

Connection  to  databnae  is  OK. 

GDI.FAILURE 

Not  connected  to  databaar, 

SEE  ALSO 

|di.cloae(3).  gdi_cxit(3).  fdljopciKS) 

AUTHOR 

Jean  T.  Anderson.  SAK!  Geophysical  Systems  Operation,  Open  Systems  Division 
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Last  change:  12/27^13  (v20.2) 


Sun  Release  4.1 


GDI_ERRCX(_FLAGS  ( 3  )  C  UBRARY  FUNCTIONS  GDI_ERR(»_FLAGS  ( 3 ) 


NAME 

gdi_ein]r_iUigs  -  retrieve  debug  ml  tlseiiiold  settings 

SYNOPSIS 

SiMiiMle  HbgdU'' 

tel 

gdijerror^lagi  (com,  debug,  thresbold) 

dbCou  ~  h  0)  thtehese  conancinr  •/ 

tel  •debug:  ^  (o)  OIH  KBUG  ON,  GDI  DEBUG  OFF.  or  GDI  ECBUG  VERBOSE  */ 

tel  •tbrabdd;  A  (o)GDrWARNliWorGDr_FATAL'*/ 

DESCRIPnON 

Erran  ree  tiandled  oo  a  connection  1^  connection  bam.  gdijenor^flagsO  retrieves  die  cuirent  settings 
of  debug  and  threshold  for  a  specified  connection. 

ARGUMENTS 

cnuu  The  database  connector.  If  NULL,  gets  global  enor  flags. 

debug  GDI_DEBUG_OFF  by  defiuilt,  if  set  to  GDI_raBUG_ON,  errors  are  ouqput  automati¬ 
cally  to  siderr.  GDI_IKBUG_VERBOSE  causes  numerous  ddnig  messages  as  well  as 
errors  and  warnings  to  be  outpSi  so  siderr. 

tbrcahoM  Controls  the  threshold  at  which  an  error  or  warning  causes  a  GDI_FAILURE.  A  thres¬ 
hold  of  GDI_WARN1NG  causes  all  warnings  ml  errors  to  be  uueiiMeted  as  failures.  A 
threshold  of  GDI^FATAL  causes  only  tetal  errors  to  be  inierpreted  as  failures. 

DIAGNOSTICS 

gdi_error_fiagsO  always  returns  GDI_SUCCESS. 

FILE 

gdi_eirorx 
SEE  ALSO 

gdi_errorjget(3).  gdi_crror_teit(3) 

AUTHOR 

B.  MacRitchie,  SAIC  Geofdiysical  Systems  Opemtioo,  Open  Systems  Division 


Sun  Release  4.1 


Last  change:  l2ffI/93  (v202) 
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GDI_ERR0R_GEr(3) 


C  LIBRARY  FUNCnONS 


GI>I_ERROR_GET(3) 


NAME 

fdi_efror _get  -  retrieve  ener  nfonnatioa  from  die  dmahwr  comiectian 

SYNOPSIS 

iiKiwic  HbgdLh" 

tat 


filijerror_ict  (conn,  crrcodc,  cntcat,  maTtwl,  statna,  aevcrity) 

dbConn 

*cann; 

h  (i)  database  connection  •/ 

tat 

^crrcodc; 

/*  (o)  qiecific  eirar  code  •/ 

char 

•crrtest; 

/*  (o)  error  text  */ 

tat 

■astfst; 

h  0)  ieagth  of  eotext  variable*/ 

tat 

*atatna; 

/*  (o)  teneral  awns  */ 

tat 

^severity; 

/*  (o)  severity  */ 

DESCRIPTION 

Emm  are  reported  on  a  connection  by  connection  basis.  gdi_enror _getO  retrieves  enor  information 
from  the  database  connector. 


ARGUMENTS 

Ihe  database  connector.  If  NULL,  global  enor  intormation  is  retrieved. 

encode 

Specific  error  code. 

errtext 

Message  text  for  the  error  code. 

nmxtext 

Size  of  the  emext  string,  controlling  how  much  text  may  be  copied  into  the  user’s  emexi 
variable. 

fftaf*** 

GDI JUCXESS  or  GDI_FAILURE. 

severity 

GDI_NQERROR,  GDI.FATAL,  or  GDI.WARNING. 

DIAGNOSTICS 

gdi^enor jgetQ  always  returns  GDI_SUCCESS. 

FILE 

gdi^errorx 
SEE  ALSO 

tdljermr_iaEB(3),  8di_error_tait(3) 

AUTHOR 

B.  MacRitchie,  SAIC  Geophysical  Systems  Operation,  Open  Systems  Division 
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Last  change:  12/27/93  (v202) 


Sun  Release  4.1 


ODl_ERRCXt_lNTr(?) 


C  LIBRARY  FUNCTIONS 


GDI  ERRCXl  INIT(3) 


NAME 

gdi_em>_init  -  initialize  encr  handling  flags 

SYNOPSIS 

ilKlade 'MbidLh'' 

iat 

|dijerrar_tait  (cou,  debug,  tbresboM,  reacnredl,  rtaenrcdS) 
dbCou  ~  *cou;  /*  (i)  darahaec  connwtion  •/ 

int  dcbag;  h  (i)  GDI  DEBUG  OFF.  GDI  IXBUG  C»4.  GDI  DEBUG  VERBOSE  */ 

tat  thnaboU;  /•  (i)ODrWARNDk}arGIM>ATAL  •/ 

tat  reacnmil:  /•  not  uaed  •/ 

tat  rcacrvcdl;  /•  not  used  *! 

DESCR1P110N 

Emm  He  on  a  conneciiop  by  conneciion  basis.  gdi_enQr_iiiitO  inHializfts  the  debug  and  dires- 

hold  flags  for  a  connector,  debug  coniiols  optional  oui^  of  errors  to  stderr.  threshold  sets 

the  level  of  error  or  warning  that  is  treated  as  a  fiulnre  by  the  GDL 

ARGUMENTS 

conn  The  connector.  If  NULL,  sets  gfobal  error  flags  sod  initializes  global  etior  indi¬ 

cators. 

debug  GDI_I«BUG_(XF  (FALSE)  by  default  If  set  to  GDI_l»BUG_ON  (TRUE),  etrors  are 
ou^Htt  auioini^cally  to  stderr.  If  set  to  GDI_KBUG_VERBOSE,  non-error  debug  mes¬ 
sages  are  output  automatically  to  stderr. 

thrcabold  Sets  the  threshold  at  which  an  enor  or  warning  causes  a  GDIJPAILURE.  A  threshold  of 
GDI_^WARNING  causes  aO  warnings  and  errors  to  be  treated  as  failures.  A  threshold  of 
GDIJ’ATAL  causes  only  fiual  eoors  to  be  treated  as  failures. 

rcaervedl  Reserved  for  future  use. 
reserved!  Reserved  for  future  use. 

DIAGNOSTICS 

gdi_eiror_initO  always  returns  GDI_SUCCESS. 

FILE 

gdijerrorx 
SEE  ALSO 

idi_eiTor_flaga(3),  tdi_errorjget(3) 

AUTHOR 

B.  MacRitchie,  SAIC  Geophysical  Systems  Operatioo,  Open  Systems  Division 


Sun  Release  4.1 


Lmt  change:  12/27/93  (v202) 
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GI>I_EXIT(3) 


C  LIBRARY  FUNCTIONS 


GDI_EXrT(3) 


NAME 

gdi_extt  -  ckMe  all  open  database  oonaectioiu 

SYNOPSIS 

MbcIimIc  *lib|dU'' 

IM 

fdijexil  0 
DESCRIPTION 

gdi_exitO  closes  all  open  database  connectiaas,  freeing  aU  database  connection  structures  (dbConn). 
DUGNOSnCS 

gdijexitO  always  retuns  GDI_SUCCESS. 

FILE 

gdi_connx 
SEE  ALSO 

fdi_cloac(3).  fdi_dcad(3).  tdi_opcB(3) 

AUTHOR 

B.  MacRitchie,  SAIC  Geophysical  Systems  Operation,  Open  Systems  Division 
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Sun  Release  4.1 


GDI_FLUSH(3) 


C  UWARY  FUNCTKMS 


GDI_FLUSH(3) 


NAME 

gdi_fliish  -  discard  unprocessed  query  results 

SYNOPSIS 

SlMtaMle -KbgdLh” 

iat 

fdi_f  ash  (oNui,  chaaao) 

dbCoaa  •coaa;  /*  (i)  comiection  •/ 

iat  chaaao;  /•  (i)  chaiuiel  number »/ 

DESCrUPTION 

gdi_flushO  dumps  any  unprocessed  query  results  from  the  mott  lecenily  query.  Fdr  (KIACLE, 

this  cancels  a  query  after  the  desired  number  of  tows  have  been  fetched  and  frees  any  resources  associ¬ 
ated  with  the  cursor.  For  SYBASE,  it  cancds  any  rows  pending  in  the  DBRCXXSS  results  bufler  in 
case  the  user  did  not  process  all  rows  in  the  rewlt  set 

ARGUMENTS 

coaa  The  datahase  connector  for  the  connection  the  channel  was  opened  on. 

chaaao  Channel  to  flu«h. 

DUGNOSnCS 

gdi_fluahO  returns  one  of  the  following  status  values. 

GDI_SUCCESS 

Succeeded  in  flushing  channel. 

GDI_FAILURE 

Flush  failed;  possibly  the  database  connection  dropped. 

FILE 

gdijchannelx 

SEE  ALSO 

gdi_abort(3) 

AUTHOR 

Jean  T.  Anderson.  SATC  Geophysical  Systems  Operation,  Open  Systems  Division 


Son  Release  4.1 


Last  change:  12427/93  (v20.2) 
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GDI_GET_ACCOUNT(  3  ) 


C  LIBRARY  FUNCnOIS 


GDI^GET_ACXXKJNT  (  3 ) 


NAME 

gdi ,_^_accouat  -  get  database  aocotnt  name  from  Aatahaw  connector 

SYNOPSIS 

Stadnde  "HbgdLh" 

tau 

fdi_fet_accoaat  (cobb,  bccobbL  Icb) 

dkCoBB  •cobb;  /*  (i)  daiabase  connection  •/ 

char  *aocouBt;  h  (o)  account  name  •/ 

int  Icb;  f*  (i)  length  of  account  argument  */ 

DESCRIPTION 

gdi _get_accoa9it0  gets  the  database  account  name  from  the  datahaar  oonnector. 
ARGUMENTS 

COBB  The  database  connector. 

account  Database  account  name  is  filled  in  by  this  routine. 

Icb  Length  of  the  accotmt  aigumenL 

DIAGNOSTICS 

gdi ,^_accountO  returns  one  of  the  following  status  values. 

GDI_SUCCESS 

Routine  succeeded. 

GDI^FAILURE 

Not  connected  to  datahaar. 

FILE 

gdi_coniix 
SEE  ALSO 

gdi _gct_databasc(3).  gdi _gct.Bodc(3) 

AUTHOR 

B.  MacRitchie,  SAIC  Geophysical  Systems  Opeiation,  Open  Systems  Division 
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Last  change:  12/27^3  (v202) 
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GDI_GET^ARRAYSTOUCTS  (  3  ) 


C  UWARY  FUNCn(»<S 


GDI_GET_ARRAYSTOUCTS  ( 3 ) 


NAME 

gdi_get_AiniySlnicts  -  Get  the  leailts  of  a  quay  io  an  anay  of  itniciuies. 

SYNOPSIS 

*iKlude '‘HbgdLh* 
ifaidude  '‘<typc>_Aatract&Ji” 

iat 

|di_fet_ArrayStnict8 
dbCOBB 
char 
void 
iat 

ArrayStractsArgs 
DESCRIPnON 

gdi _get_AnayStnictsO  submits  a  quay  to  a  datahase  and  returns  the  results  in  an  anay  of  structures. 
The  array  of  structures  is  allocated  by  gdi _ga_AmvSlruct80.  It  is  the  reqxmsibility  of  the  ^qdication 
to  free  the  array.  Headers  containing  a  sirudure  definition  with  fields  matching  the  ctdumns  of  the 
query  are  created  with  gdi _gen_Astructs(l). 

The  structure  must  contain  a  field  for  each  column  in  the  query  howeva  the  columns  need  not  be  in  the 
same  orda  as  the  fields  in  the  structure.  The  structure  m^  contain  more  fields  than  those  needed  to 
match  the  query  columns.  The  additional  fields  will  be  filled  with  defiault  or  'TiA”  values. 

Note  that  the  structure  generated  by  gdi _gen_Astnicts(l)  matches  the  columns  of  a  query,  not  the 
columns  of  a  particular  table.  A  query  sekering  a  sin^  column  Cram  a  taUe  or  a  query  selecting 
columns  Crom  several  laUes  may  be  used  to  generate  the  stniciure.  The  only  restriction  is  that  each 
etdumn  must  be  identified  by  a  unique  name. 

ARGUMENTS 

coon  The  «tatni<a«>  cotmector. 

query  The  database  query  to  be  submitted  to  the  database. 

array  The  address  of  the  array  pointer  to  receive  the  query  results.  The  results  are  allocated  by 
gdi _get_AnayStnictsO.  Note:  It  is  the  respoHsUrility  of  the  appUattion  to  fr^  the  struc¬ 
ture. 

Buxrcc  The  maximum  mnnba  of  records,  or  tiqrles,  to  be  retnmed  fiom  the  database. 

type  A  description  of  the  array  structure,  the  "NA”  values  and  otha  mfiorroation  needed  to 

process  the  resultt  for  outpuL  The  description  is  contained  in  the  ”<type>  Astructs.h" 
heada. 


(conn,  query,  array,  aumrec, 
vcona;  /*  (i)  ^  cormeclioo  */ 

vqnery;  /•  (i)  database  query  •/ 

**array:  /•  (o)  array  of  structs  */ 

aaazrec;  /*  (i)  maximum  number  ttf  records  lo  retrieve  */ 

•type;  /*  0)  structure  definition  */ 


EXAMPLE 


The  following  example  uses  a  heada  dunqted  by  gdi _gen_Asiructs(l)  using  the  query,  "select  *  from 
arrival”.  The  structure  definition  in  arrival_Astructs.h  is  shmvn  below. 

typedef  struct  arrival  ( 

efav  ata[7); 

doitble  time; 

long  arid; 

long  jdaie; 

ln«^  t— «iH- 

fhantrt! 

ch«  chan  [9]; 

cfav  iphaae  [9]; 

chv  stypePl; 
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C  LIBRARY  FUNCTIONS 


GDI  GET  ARRAYSTRUCTS(3) 


double 

awmiith; 

dniitUf 

delaz; 

double 

alow; 

doable 

delalo; 

dodUe 

etna; 

reel; 

double 

•any. 

(loyblf 

per. 

iQgat; 

char 

clip  [2): 

char 

fin  PI; 

BBf 

char 

qmd  [2]  ; 

char 

autfa  [Ifi]; 

long 

commid; 

char 

Iddate  [18]; 

)  Arrival; 

The  fcdlowing  code  segment  retrieves  data  from  the  database,  diqtlays  the  results,  and  then  free’s  the 
result  structure. 

iinclude  libgdiJi'' 
finclude  ''arrival_AsttuctsJi'' 
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GDI_GET_ARRAYSTRUCTS  (  3  )  C  LIBRARY  FUI«mONS  GDI_GET_ARRA YSTRUCTS  ( 3 ) 


bee  (tuples}; 


DIAGNOSTICS 

gdi _get_AmySiiuctsO  retunis  the  number  of  tuples  retrieved  if  successfiiL  otherwise  it  reuirns  -1. 
Error  codes  and  messages  may  be  retrieved  from  tte  datahare  connector  with  gdi_emw_get(3). 

FILE 

gdi_ArTayStructsx,  gdi_AmyStnictsJi 
SEE  ALSO 

gdijMid_AiTayStriict8(3),  gdi_crrorjget(3).  idij|cn_Attructs(l) 

AUTHOR 

B.  MacRitchie.  SAIC  Geophysical  Systems  Operation,  Open  Systems  Division 
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GDI_GET_COUNTER  (  3  ) 


C  LIBRARY  FUNCTKX4S 


GDI_OET_<»UNTER  (  3 ) 


NAME 

gdi _get_oouiiier  -  get  unique  datalunr  key(s) 

SYNOPSIS 

«iMlwk  "IbidLfe'' 

int 

gdi_getjcoiiBUr 
dbCou 
char 
chv 
int 
img 

DESCRIPTION 

gdi _get_couiiierO  assigns  unique  sequential  manbcR  to  ini^  identifiers,  called  keys,  in  the  database. 
It  manages  key  assignment  in  the  named  table,  which  stores  the  name  of  the  key  in  (keyname)  and  the 
last  number  assigned  (keyvalm).  Given  the  name  of  the  key  in  keyname,  gdi _get_coimier  0  retrieves 
its  value  fiom  the  database,  incremeats  it  by  die  amount  in  iikeyr.  writes  it  back  to  the  database,  and 
stares  the  result  in  keyvalne  to  be  used  by  the  calliag  application. 

ARGUMENTS 

conn 

tabicname 
keyname 
nkeys 
keyvaluc 
C  EXAMPLES 

The  following  example  gets  one  mesgid  key  Cram  the  lastid  taUe  accessible  by  the  current  account: 
finclude  ’UbgdiJi'' 


Ibe  database  connector. 

Name  <tf  the  table  used  for  di^wising  key  values. 
Name  the  key. 

Number  of  consecutive  key  values  to  assign. 
Highest  unique  key  value  requested. 


*keyaBM: 

■kq»: 

*keyvalne; 


keynamct  nkeys,  k^valne) 

(i)  database  connection 
®  name  of  key  table 
^  name  of  key 
^  number  of  keys  requested 
(o)  highest  key  value  assigped 


dbConn 

*CQnn; 

char 

char 

int 

int 

/«  variables  for  call  to  gdi  jgetjcounter  */ 
*aMeQame  «  "lastid";  h  name  of  k^  table  */ 
«keyname  «  "mesgid":  h  name  of  key  */ 
nk^;  h  number  of  keys  to  get 

key^  h  unique  key  v^ue  */ 

int 

char 

h  enor  handling  variaUes  */ 
envjcode,  status,  sevens 
envjstring  [GIH_ERRCXI_S1S  *  1]; 

...  epeii  a  database  connection  ... 

key^l; 

if  ((gdi_get  cotmterfcoon,  taUenaroe,  keyname,  nkeys,  Akeyval)) !«  GDI  SIJCCESS) 

{ 

gdijenor  jex  (conn.  Renorjoode,  enorjnring.  sizeof(enor_string). 
Astatus,  ftseve^); 

Qnintf  (atdenr,  "Enor  %d:  *%sNi”.  error  code,  enw  string); 
exit  (GDI_FAIL11RE); 
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GDI_GET_COUNTER  (  3 ) 


) 

If  00  eiror  occurred,  keyval  now  contains  one  unique  value  the  ntplication  may  use. 

If  Hieys  was  S,  keyval  would  contain  the  iagbest  of  the  S  unique  ids  the  application  may  use.  For 
example,  if  keyval  is  10.  the  apfdicatiao  may  use  keys  6  through  10. 

If  akeys  was  0,  keyval  would  contain  the  last  value  assigned-and  the  calling  apidication  should  not  use 
it  since  it  was  alr^y  used  by  another  plication 

DATABASE  CONFIGURATION 

The  table  must  be  created;  for  example: 

SYBASE: 

create  table  lastid  ( 

keyname  char(lS)  not  nuU, 

ki^rvalue  int  not  nidi, 

datetime  null) 

ORACLE: 

create  table  lastid  ( 

keyname  varchar(lS)  not  null, 

keyvalue  number(8)  not  null, 

Iddate  date): 

The  keyname  field  contains  the  name  of  an  integm'  primary  or  foreign  key  such  as  mesgid.  The  key- 
value  field  contains  the  last  value  which  was  uaed  for  the  key  in  keyname.  The  Iddate  field  contains  the 
last  time  keyname  was  updated. 

The  table  must  be  populated  with  the  qipropriate  keynames  for  the  »tamha«i»  installation.  The  following 
examples  demonstrate  how  to  insert  a  new  key  and  initialise  it  to  0: 

SYBASE:  insert  into  lastid  (keyname,  keyvalue,  Iddate)  values  (’mesgid',  0,  getdate  ( )) 
ORACLE:  insert  into  lastid  (keyname,  keyvalue,  Iddate)  values  (’arid’,  0.  sysdate); 

The  lastid  table  should  be  accessible  to  all  who  need  to  acquire  keys: 
grant  select,  qxlate  on  lastid  to  public 

NOTES 

gdi _get_countetO  eqdidtly  commits  the  transaction  on  success,  or  mils  it  bock  if  an  error  occurs.  Key 
values  should  be  acquired  before  starting  an  S(^  work  groq>  since  the  gdi _get_counterO  is  a  work 
group  in  and  of  itself. 

Currendy  there  is  no  mechanism  for  recovering  lost  keys.  For  example,  if  an  qjplication  gets  a  key 
value  and  the  system  goes  down  before  the  application  has  used  the  value,  it  will  be  lost 

DIAGNOSTICS 

The  ftdlowing  codes  are  returned  fiom  gdi jgetjcounterO  to  the  calling  apifiicatioo: 

GDI_^SUCCESS 

This  routine  succeeded. 

GDI_FAILURE 

An  error  occurred.  Specific  error  code  and  message  may  be  retrieved  with 
gdi_eirar _getO. 

FILE 

gdi ,^_oounter.c 
SEE  ALSO 
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gdi^eirar _get  (3) 

AUTHOR 

Jean  Andencn.  SAIC  Geophysical  Systoms  Opentioo.  Open  Systems  IMvisioo 
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NAME 

yli^_daabMe  -  get  daiabMe  name  from  thmbMc  comector 
SYNOPSIS 

PiMtade 'HI»|dLk'' 

tait 

|di _getjdatalMMe  (con,  difhaae,  lea) 

dbCooB  «coui;  /•  (i)  ditahiw!  connection  •/ 

char  «databaae;  /*  (o)  datahaar  name  •/ 

bit  ka;  /*  (i)  length  of  databaae  afguntent  */ 

DESCRIPTION 

gdijpt^dattbaaeO  gets  the  databaae  name  from  the  datahasr  connector. 
ARGUMENTS 

coaa  The  database  conaector. 

databaae  Databaae  name  is  filled  in  by  this  routine. 

lea  Length  of  the  dmohiue  atgumem. 

DIAGNOSneS 

gdi,jet_databaseO  returns  one  of  the  following  status  values. 

GDISUCCESS 

Routine  succeeded. 

GDIFAILURE 

Not  connected  to  database. 

FILE 

gdi^connx 
SEE  ALSO 

gdi_getjKCoaat(3),  gdi_get_aode(3) 

AUTHOR 

B.  MacRitchie,  SAIC  Geophysical  Systems  Operation.  Open  Systems  Division 
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GDI  GET  DBOPnON(3) 


C  LIBRARY  FUNCnONS 


GDI  GET  I»CX>TION(3) 


NAME 

gdijget^dboption  -  Get  the  sale  of  a  daahase  optiao 

SYNOPSIS 

ftaKtaHk  UbidU'' 

iat 

|di  jpt  dboptkNi  (con,  chauM,  dptka,  acttiag) 
dbCoaa  *caaa;  h  0)  daabase  conaeriinn  •/ 

iat  chaaao;  h  0)  cbMoel  auate  */ 

dbOptioa  optioa;  /*  (i)  cptiao  to  be  set  */ 

char  «acttiac;  /*  (o)  vidue  of  the  ofitioa  */ 

tat  taU;  /*  CO  leagth  of  •setting*  */ 


DESCRIPnON 

The  «»«»»*■  of  various  **•*•*'*•*  optioiis  nay  be  retrieved  by  gdijgctjJboptionO.  Some  options  ate  set  at 
the  connectioo  level  others  a  the  channel  level  Moat  options  are  spedfic  to  a  daabese  vendor.  If  the 
value  is  requested  for  an  optiao  which  is  not  applicable  to  the  vendor,  setting  is  left  untouched. 

A  Autihaai.  option  may  be  Set  through  gdi ^.dboptiao(3).  Some  options,  such  as  GDI_PRCX:_C.  are 
not  but  their  states  may  still  be  retrieved. 

Ihe  connector. 

Hie  number,  chaiuio  is  ignored  by  options  that  are  set  a  the  connector  level. 

The  option  to  be  retrieved. 

A  char  army  in  which  the  setting  string  will  be  stored. 

The  kngdi  of  die  setting  anay. 

OPTIONS 

Ihe  following  options  may  be  retrieved: 

GDI_VERSION 

~  The  version  number  of  the  GDI  Ubray. 

GDI  AUTO  COMMIT 

~  Oracle.  ”1"  if  auto  wwimh  is  on.  ”0”  if  off.  Auto  commit  is  by  defiulL  If  auto 
f^mit  is  on,  each  is  automatically  committed  as  soon  as  it  is  exe¬ 

cuted.  If  cnminit  is  off.  *  sttiements  are  treated  as  port  of  a  transaction 
which  is  explicitly  or  roQed  bock  widi  gdi^commitO  or  gd_roIlbackO. 

GDI  PRO  C 

Oracle.  ”1"  if  Fto*C  mode  is  enabled,  otherwise  "0".  The  op^  applies  to  the  entire 
^yinwetWi-  Rto*C  is  enabled  by  opeoiiig  the  connection  using  onclejopenO-  The 
option  can  not  be  changed  after  the  connection  has  been  opened. 

USAGE 

The  exanqile  below  gets  the  setting  of  GDI_AUTp_OOMMrr. 

dbCoon  *0000; 

char  «aetting; 

int  ien; 

...  initialize  and  open  a  coonectian  ... 

if  (gdi _^get  dboptioo  (conn.  GDI^I^FALUTjCHAN.  GDI_AUTO_COMMIT, 

Asetting.  Alen)  is  GDI_SUCOESS) 


ARGUMENTS 

eonn 

chaano 

option 

SfHtsg 

Icn 
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( 

) 


...  handle  enor ... 


primf  CAuto  Camiiut «  %a0,  settiiig); 


DUGNOSnCS 

gdi^get^dboptionO  letums  one  of  the  foUowoig  Mnis  values: 
GDI_SUCCESS 

Operatioa  succeeded. 

GDI_FAILURE 

Opendoo  failed;  possibly  the  connection  dropped. 

FILE 

gdi_optionx 
SEE  ALSO 

|iU_cownit(3).  gdi_ronMck(3).  fdi_act_dboption(3).  oncle_opcn(3) 
AUTHOR 

B.  MacRitchie.  SAIC  Geophysical  Systems  Openlion,  Open  Sysienu  Division 
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C  LIBRARY  FUNCnmS 


GDI_GET_NODE(3) 


NAME 

gdi_get_iiode  -  get  datibMe  node  name  finom  rtatabmic  connector 

SYNOPSIS 

ilMiade  "HbgdLh" 

int 

idi_fet_nodc  (conn,  node,  lea) 

dbCona  *cau:  /•  (i)  datdhnsf  connection  •/ 

char  *aodc;  /*  (o)  node  name  */ 

iat  lea;  /•  (i)  Ingth  of  node  argument  */ 

DESCRIPTION 

gdi _get_nodeO  gets  the  databnae  node  name  finm  the  datdwir  conaedor. 
ARGUMENTS 

cona  The  datahasr  connectar. 

aode  Database  node  name  is  filled  in  by  this  routine, 

ka  Length  of  the  node  a^gnment 

DIAGNOSTICS 

gdi jget_nodeO  returns  one  of  the  following  status  values. 

GDI_SUCCESS 

Routine  succeeded. 

GDI_FAILURE 

Not  connected  10  database. 

FILE 

gdijconnx 
SEE  ALSO 

idi_gc(jKcoont(3).  gdij|ct_database(3) 

AUTHOR 

B.  MacRitchie.  SAIC  Geophysical  Systems  Openiioo,  Open  Systems  Division 
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C  LIBRARY  FUNCTIONS 
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NAME 

gdi_Bet_veiidon  -  get  a  list  of  the  veadocs  suppofted  hy  GDI 
SYNOPSIS 

ilMiiidc  "HbfdLh” 

char 

|di_|ct_vcBdon  0 
DESCRIPnON 

gdi j{et_veodonO  ictums  a  NULL  temunated  anay  of  strings  the  names  of  the  riatahasy 

don  supiXMed  by  the  GDI. 

SAMPLE  CODE 

chsr  **vendors; 
int  i; 

vendofs  «  gdi _get_vendors  0: 

fprintf  (stdout.  The  supported  GDI  vendors  aref^”); 

for  (i  s  0;  vendors[il  Is  NULL;  H-f) 

fixintf  (stdout,  vendQts(i]): 


fflush  (stdout): 


FILE 

gdi_Iinkx 

AirraoR 

B.  MacRitchie,  SAIC  Geophysical  Systems  Operation.  C^xn  Systems  Division 


vcn- 


Sun  Release  4.1 


Last  change:  9/21/93  (vl8.1) 


29 


GDI_IN1T(3) 


C  UffitARY  FUNCTIONS 


GDI_1NIT(3) 


NAME 

gdi.iiiit  -  initialize  the  GDI 

SYNOPSIS 

«Md«de  "MbfdLh* 

hit 

fdi_iBit  (appaam,  fdlhoBM) 

char  *appaaBc;  /*  (i)  application  name*/ 

char  •liUhoaM:  h  (i)  GN  home  dimctory*/ 

DESCRIPTION 

gdi^initO  initializer  the  GDI. 

ARGUMENTS 

appaaam  ^iplicatiao  name  (actual  name  of  the  executable). 

li**TitrT  Directory  where  GDI  is  mfilixt  Hr  GDI  searches  gdawme/lib  for  the  GDI  vendor 
intfrfae*L  Hbtarics  to  bc  dynamically  located.  If  gdi_initO  has  not  been  cdled  or  if 
gdihnwMt  is  NULL  or  an  enqxy  string,  **.  then  the  GDI  will  use  the  environment  vari¬ 
able.  GDIHOME. 

DIAGNOSTICS 

gdi_iiatO  lenims  one  of  the  following  status  values. 

GDI_SUCCESS 

GDI  successAilly  initialiml 

GDI^^FAILIIRE 

Failure  in  initializatian,  possibly  the  application  name  was  invalid. 

FILE 

gdi_^linkx 

AUTHOR 

B.  MacRitchie,  SAIC  Geophysical  Systems  Operation,  Open  Systems  Divisioo 
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NAME 

gdi_iiiMit  -  Inacft  data  into  a  datahay  table 

SYNOPSIS 

SiKiiidc  "HbgdLh* 

bit 

|di_iBaei1  (cobb,  table_BaBM,  daiaiB) 
dbCoBB  •cou; 

char  •tabk_BaBM; 

dbObJ  •datata; 

DESCRIPTION 

gdi_insertO  inaerts  data  into  a  datahaar  table.  The  data  is  contained  in  tbe  tuples  of  the  dbOty.  The 
ttfie  constructor  is  used  to  access  the  data  in  the  tuples.  Tlie  column  definitioas  in  the  dbObj  are  used 
to  identify  the  columns  of  the  dmahasr  that  are  to  receive  the  data. 

Data  is  inserted  using  the  fastest  mode  for  the  particular  dathhaafs  In  the  case  of  ORACLE,  data  is 
inserted  using  anay  inserts.  SYBASE  inserts  use  SYBASE’S  bulk  copy  mechanism. 

ARGUMENTS 

COBB  The  database  connector. 

table_BaBM  Tbe  name  of  tbe  table  into  which  the  data  is  to  be  inaetted. 

datalB  The  dbOty  containing  the  data  to  be  inserted. 

DIAGNOSTICS 

gdi^insertO  returns  one  of  the  ftdlowing  status  values: 

GDI_SUCCESS 

Insert  executed  successfully. 

GDI_PAILIIRE 

Not  connected  to  database  or  error  executing  command. 

FILE 

gdi_insertx 

SEE  ALSO 

gdi_submtt(3) 

AUTHOR 

B.  MacRitchie,  SAIC  Geophysical  Systems  C^teratioo,  Open  Systems  Division 


/«  (i)  (fatfabaae  connection  */ 

/«  (i)  rtatahaar  table  name  •/ 

/*  (o)  dbObj  -  data  to  be  inaeried  */ 
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C  LIBRARY  FUNCnONS 


GDI_OBJ_CREATE(3) 


NAME 

gdi_obj_cieaie  -  allocate  a  new  dbCX>j 

SYNOPSIS 

ftadude  "HbtdLh" 

dbObJ* 

|di_obJ_ci«ate  (coutr) 

dbCoB^  •coutr;  /•  0)  data  cooatiuciar  •/ 

DESCRIPnON 

gdi_obj_cicateO  aHocates  a  new  dbOt^.  The  coutnidor  pointed  to  by  constr  is  copied  into  the  dbObj 
oonstni^  field  of  the  new  dbObj.  If  gdijobjjoeateO  is  ncoeofiiL  a  pointer  to  the  new  dbObj  is 
letuned.  NULL  is  retunied  if  an  cnor  oocmed. 

The  dbOhj  allocated  should  be  aooeased  using  the  macros  and  fimctkms  provided  by  ifitgilLa.  Examples 
may  be  found  in  the  test  routine  libsrc/Ubgaidb/test/tajlbobj.c. 

ARGUMENTS 

constr  This  is  the  tigile  ”coiistnictor”  which  specifies  pomtets  to  fimctions  that  access  the  titles 
in  the  dbObj.  A  default  constructors  is  provided  in  libgdiJi.  The  GDI_I^AULT  ctm- 
stractor  can  be  used  when  calling  gdi_obJ[_createO.  unless  the  user  nmots  to  specify  a 
different  tuple  structure.  Additional  coutnictors  include  GDIJTURBO  and  GDI_SD1. 

DIAGNOSneS 

gdi_obj_createO  returns  a  pointer  to  the  new  tBfObJ  if  successfiiL  or  NULL  if  an  error  occurred. 

FILE 

gdi^dbobjx 
SEE  ALSO 

tdijobjjdestroy(3),  gdijnbadtCS) 

AUTHOR 

B.  MacRitchie,  SAIC  Geophysical  Systems  Operation,  Open  Systems  Division 
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GDI_OBJ_DESTROY  (  3  ) 


C  LIBRARY  FUNCTIONS 


GDI_OBJ_E®STROY  ( 3 ) 


NAME 

gdi^ob^desm^  -  free  memoiy  lUcxated  for  a  dbOlg 

SYNOPSIS 

Sfadwk  "HbcdU* 

tat 

tdi jobJ_datroy  (obj) 

dbObJ  *obJ;  /*  (i)  dattbaae.  object  *! 

DESCRIPnON 

The  dbObj  is  a  generic  structure  containiiig  database  data,  status  and  error  information.  A  dbObj  is 
normally  created  when  a  user  calls  a  database  access  function,  such  as  gdi_submitO-  After  extracting 
the  mfotmatioo  returned  in  the  dbObj,  the  user  should  call  gdijobj^destroyO  to  fiee  the  memory  allo¬ 
cated  to  the  structure. 

ARGUMENTS 

obJ  A  object  structure  containing  status,  etron  and  other  results  of  a  dataha.se  com¬ 

mand. 

DIAGNOSTICS 

gdi_obj_destroyO  always  returns  GDI_SUCCESS. 

PILE 

gdi_dbob|x 
SEE  ALSO 

fdijobJ_crcate(3),  gdi_snbnilt(3) 

AUTHOR 

B.  MacRitchie.  SAIC  Geophysical  Systems  Operation,  Open  Systems  Division 


Sun  Release  4.1 


Last  change:  12^7^13  (v20.2) 
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0DI_C»EN(3) 


C  LIBRARY  FUNCTIONS 


GDl_OPEN(3) 


NAME 

gdi_open  -  esaMiah  a  connection  to  the  datahair 

SYNOPSIS 

«iacliide  "libgdU'' 

dbConn  * 


Idijopen  (vendor,  noconnt,  piMword,  datahaar,  acrvcr,  appnaaae) 


char 

^vendor; 

/♦  (i)  database  vendor  ♦/ 

char 

^account; 

/♦  (i)  database  account  ♦/ 

Aar 

vpaasword; 

/*  (i)  account  password  ♦/ 

char 

♦datahaar; 

/*  (i)  database  or  machine.  ♦/ 

char 

♦server; 

/*  (i)  database  server  ♦/ 

char 

♦appnaaM; 

/*  (i)  application  name  ♦/ 

DESCRIPTION 

Given  the  valid  Anah— #■.  connect  infonnation.  gdijopenQ  opens  a  daahaae  connection  to  the  specified 
Hatahflw  vendor,  and  creates  and  initializes  the  dbCotui  database  connection  structure. 

More  than  one  oonnectian  may  be  estaMished.  including  a  mix  of  database  vendors.  Two  channels  for 
each  connection  ate  opened.  More  channels  may  be  opened  with  gdi  jopen_channelO. 

ARGUMENTS 

Many  of  these  parameters  may  be  NULL  dqxnding  on  the  database  vendor. 

voMkir  Reiiuiied  parameter.  NULL-terminated  string  containing  the  name  of  the  database  ven¬ 
dor.  UbgdLh  includes  string  macros  for  each  database  siqipotted  (GDI  MCMTAGE  S, 
GDI_ORA<XE_S.  GDI_POSTGRES_S,  GDIJYBASE_S).  A  GDI_ORACLE_PRO(f  S 
veadw  option  also  availaUe.  whi(±  estaUidtes  a  pt^c  connectkm  to  (BIACLE.  This 
allows  pragnmmers  to  link  in  pto*c  routines. 

aoconat  NULL-terminated  string  containing  the  datahaar,  account  or  user  name.  CBIACXE 
account  names  may  include  the  password  or  the  entiie  CXIACLE  Version  6  database  con¬ 
nect  string;  for  example,  gdidemo/gdkiemo  or  giSdemo/gdklmo(^t:5bymir:dev. 

paasword  NULL-tenninated  string  containing  the  account  password.  May  be  NULL  for  (XIACXE 
if  the  acccmt  arguroeat  includes  the  password.  Mqr  be  NULL  for  other  databases  if  a 
NULL  password  is  diowed  for  the  associated  account 

databaae  NULL-tenninated  string  containing  the  database  name  for  MONTAGE,  POSTGRES,  (x^ 
SYBASE,  or  the  SQL*Net  connect  stfing  kdcryniirdev)  for  (XIACLE.  May  be 
NULL  for  ORACLE  if  the  connea  siring  is  included  in  die  account  argument,  or  if 
either  the  TWOJTASK  or  ORACLE_SlD  environment  variables  are  set  If  NULL  for  all 
databases  excqxCXlACLE,  die  user’s  defult  datahair  is  opened. 

server  Name  of  the  database  server.  May  be  NULL 
appname  ^ifdicatioo  name  (only  used  by  SYBASE).  Mr^  be  NULL. 

DIAGNOSnCS 

If  the  attempt  to  open  a  connection  fails,  the  dbConn  leturned  will  be  NULL 

FILE 

gdi_CQimx 

SEE  ALSO 

gdijclose(3).  fdi_dcad(3).  idijexit(3).  gdi.jcl_aoconat(3).  gdi _|etjdatabase(3).  gdi_get_node(3), 
gdij|et_vcndors(3),  gdi_opcnjAaaMl(3).  oradropcB(3) 

AUTHOR 
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GDI_0PEN_CHANNEL(3) 


C  LIBRARY  FUNCnONS 


GDI_C»»EN_CHANNEL  ( 3 ) 


NAME 

gdi^openjchannel  -  open  additioittl  channel  oo  a  specified  daiahaar  connection 

SYNOPSIS 

iinctwle  -HbgdU* 


int 

fdi jopeB_cluMBcl  (coaa,  chanao) 

dbCooii  «caui;  h  (i)  daiabaae  connection  •/ 

int  chaano;  /*  (o)  channel  number  address  •/ 


DESCRIPTION 

A  connection  (dbConn)  to  the  database  taxf  have  muUqde  query  channels.  A  channel  is  an 
MI_CX>NNECnQN  for  MONTAGE,  a  cursor  for  ORACLE,  a  portal  for  POSTQRES.  and  a  DBPRO- 
C^S  for  SYBASE.  For  example,  at  the  time  an  ORAQJE  connection  is  estabiished,  two  channels 
Ccorsors'O  are  automatically  opoed.  gdijopeojchanoelO  opens  additional  channels. 

ARGUMENTS 

conn  The  connector  for  the  connection  on  which  to  open  the  channel, 

chanao  Channel  number.  The  number  gets  filled  in  by  this  routine. 

DIAGNOSTICS 

gdijopenjchannelO  returns  one  of  the  foUowiiig  status  values. 

GDI_SUCCESS 

Succeeded  in  opening  channel. 

GDI^FAILUBE 

Could  not  open  channel. 


FILE 

gdi_channelx 
SEE  ALSO 

gdijChaBBel_is_opcB(3),  |di_close_daaBel(3) 

AUTHOR 

B.  MacRitchie.  SAIC  Geophysical  Systems  Operatioo.  Open  Systems  Divisian 
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ODI_PRINT_COLDEFS  (  3  ) 


C  LIBRARY  FUNCTIONS 


GDI_PRINT_OOLDEFS  (  3 ) 


NAME 

gdi  j)rint_col(kfs  -  oaqwt  cohunn  definitions  to  stdout 

SYNOPSIS 

fiMliide  "HbgdLh" 

int 

gdijirint^coldcfs  (obj) 

dbObj  "  *obj:  h  (i)  datrfwse  data  object  *! 

DESCRIPTION 

gdijnntjooldefsO  prims  the  g«iM«n  definitions  of  the  dathbase  object,  dbObj,  to  stdout.  To  prim  the 
dbObj  UK  gdi_print_dbotyO.  To  prim  the  actual  dma  use  gdi jnmjiqtlesO. 

Ctdunin  attributes  printed  are: 

NasM  column  name. 

Null?  is  a  NuO  allowed  for  this  column?  1  if  Null  is  permitted.  0  if  not 

Ctjrpe  int^er  values  representing  "C  data  types  as  defined  in  the  include  file  libgdi.h, 

for  examjde:  M_INTEGER,  M_STR1NG. 

StrSiic  string  length  if  column  is  a  string  type. 

ArmySiie  anay  length  if  column  is  an  anay  type. 

Free  database  precision  value. 

Scale  databme  scale  value. 

Dbtype  int^er  values  iqweseatiiig  database  data  ^pes  as  defined  in  the  libgdLh.  For  ORACLE, 
the  conventian  GDI_(XIA_CHAR,  GDI_ORA_NUMBER,  etc.  is  used. 

DbtypeSir  human  readable  fqiresentation  of  the  datahase  Qrpe. 

ARGUMENTS 

obJ  Hie  database  dma  object 

DIAGNOSTICS 

gdijnint_ooldefsO  returns  one  of  the  ftdlowing  status  values. 

GDI_SUCCESS 

NO  problem  outputting  the  ctAimn  definitioos. 

GDI_FAILURE 

NULL  dbObj  passed  ia 

FILE 

gdijxintx 
SEE  ALSO 

fdijirint_coaB(3),  gdij>rintjlbobJ(3).  gdijNriBt_taple8(3) 

AUTHOR 

Mari  Mortell.  SAIC  Geophysical  Systems  Opetation 


Sun  Release  4.1 


Last  change:  12f3^l93  (v20.2) 
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GDI_PIUNT_CONN  (  3  ) 


C  LIBRARY  FUNCnOfS 


GDI_PRINT_CONN(3) 


NAME 

gdij>niU_conii  -  output  the  contents  of  the  datahwc.  connection  s&ucmre  to  stdout 

SYNOPSIS 

MiKle  "HbfdUi" 

iat 

|di_priBtjoou  (COBB) 

dbCoBB  '  *cobb;  I*  (i)  databose  connectiao  */ 

DESCRIPTION 

gdijprintjOQnnO  prints  the  contents  ci  the  dsiahaie  connection  stiucture,  dbCom,  to  stdout.  If  a  con¬ 
nection  to  a  vendor  has  been  made,  the  oonieats  of  the  vendor  specific  connectioo  are  also  printed. 

ARGUMENTS 

COBB  The  database  connector. 

DIAGNOSTICS 

gdijJtintjoonnO  returns  one  of  the  following  status  values. 

GDI_S11CCESS 

No  proUem  outputting  dbCom. 

GDI.FAILURE 

NULL  dbConn  passed  in. 

FILE 

gdijxintx 

SEE  ALSO 

gdij»riBt_dbobJ(3) 

AUTHOR 

B.  MacRitchie.  SAIC  Geophysical  Systems  Operatioo.  Open  Systems  Division 
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GDI^^PRINT^DBOBJ  ( 3 ) 


C  LIBRARY  FUNCTIONS 


GDI_PRINT_DBOBJ  ( 3 ) 


NAME 

gdij)rint_dbobj  -  ot^put  dbObj  oontents  to  atdout 

SYNOPSIS 

Ptadodc  "HbgdLh" 


iat 

|di_prbit  dbobJ  (obj) 

dbObJ  '  «obJ;  /•(Oobj*/ 

DESCRIPTION 

gdijprint_dbobjO  outputs  the  contents  of  the  (htshMe  object,  dbObj,  to  adou.  To  print  the  column 
definitions  use  gdijnntjctridefsO*  To  print  the  actual  data  use  gdi_piiiit_tupiesO- 


dbObj  attributes 
Affected  Rows 
Tuples 
Columns 


printed  are: 

The  number  of  rows  affected  by  the  dathhatr  umement. 
The  number  of  rows  of  data  stored  in  the  dbObj. 

The  number  of  columns  in  each  row. 


Status 


The  return  status  of  the  database  statement. 


More  Rows  gdi^submitO  allows  a  limit  to  be  specified  on  the  number  rows  returned.  ”M(»e 
Rows*  is  TRUE  if  more  data  exists  in  the  datahasr  which  satisfies  the  query  than  were 
returned. 


Query 


The  datahasf  statement 


ARGUMENTS 

obj  The  databnsr  object 

DIAGNOSTICS 

gdi  jirint_dbobjO  temrns  one  of  the  following  status  values. 

GDI^SUCCESS 

No  problem  outputting  dbObj. 

GDI_FAILURE 

NULL  dbObj  passed  in. 


FILE 

gdijaintc 
SEE  ALSO 

gdi_priat_coldcr8(3),  gdi_print_tnplca(3) 

AUTHOR 

Mari  Mortell,  SAIC  Geophysical  Systems  Opemtioo 


Sun  Rdease  4.1 


Last  change:  (v20.2) 
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GDI_PRINT_TUPLES  (  3  ) 


C  LIBRARY  FUNCTIONS 


GDI_PRINT_TUPLES  ( 3 ) 


NAME 

gdi_pnnt_tiiples  -  print  tuple  data  to  stdout 

SYNOPSIS 

PiMiiidc  "HbgdLh" 

tat 

gdi  print 
dbObJ 
tat 
tat 

DESCRIPTION 

gdi  j>int_tu|desO  prints  the  tqile  data  in  the  databnar  object.  dbObj,  to  sidout.  To  print  the  dbObj  use 
gdi_print_dbobJO-  To  print  the  column  definitions  nae  gdjjrintjcolde&O. 

Specifying  GDIJFKEDJSPACE  causes  the  tuples  to  be  printed  in  tabular  fonn.  Numbers  are  right 
justified.  Strings  are  left  justified.  GDI_DELDdIIED.  prims  a  comma  without  adiite  space  between 
fields.  Strings  and  chars  are  encloaed  in  double  quotes.  This  output  was  intended  to  be  a  flat  file  fen-- 
mat  compatible  with  a  number  of  database  vendocs.  The  column  name  headings  can  be  enabled  or  dis¬ 
abled. 

ARGUMENTS 

obj  The  data  object 

format  GDI_FIXED_SPACE  or  GDI^DEUMIIED. 

header  TRUE  to  enable  the  output  of  column  name  headings.  FALSE  for  data  only. 
DIAGNOSTICS 

gdijirint^mplesO  returns  one  of  the  following  status  values. 

GDI^SUCCESS 

No  problem  outputting  tqdes. 

GDI^FAILURE 

NULL  dbOfy  passed  in. 

PILE 

gdi_printc 
SEE  ALSO 

gdij»riat_coldcfs(3),  gdijNrtatjdbobJO) 

AUTHOR 

Mari  Moriell  SAIC  Geophysical  Systems  Opemtioa 


tuples  (dbobJ.  format,  header) 

*dboltJ;  /*  0)  object  */ 

format;  /*  (i)  GDI_FIXED_SPACE  or  GDI_0ELIM1TED  */ 

header;  /*  (i)  IRl^  fat  column  name  headings,  FALSE  for  data  only  */ 
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GDI_R0LLBACK(3) 


C  LIBRARY  FUNCTIONS 


GDI_ROLLBACK(3) 


NAME 

gdi_roaback  -  rolllMck  cuntnt  imsactiaa 

SYNOPSIS 

iiBdiide  "Bb^lLh" 

fait 

|di_roDlMCfc  (conn,  chasao,  tnui_MUM) 
dbCou  *c(m;  h  (i)  dttfabaie  coonectioo  V 

iat  fhaaao;  /*  (i)  chaonel  number  */ 

char  •traa_aaaM:  /*  (i)  inmsactioo  name  *l 

DESCRIPnON 

A  duabaae  iiansaciioa  is  a  statement,  or  statentfints.  treated  as  an  atomic  unit  gcli_ioUbackO  ends  the 
cunent  transactian  and  cancels  aU  peadtog  changes  to  the  database. 

Note  that  transaction  management  is  implemeated  slightly  differently  in  all  the  databases  the  gdi  sup¬ 
ports. 

ARGUMENTS 

conn  The  database  connector. 

channo  The  chaonel  number  (SYBASE  and  M^TTAGE).  SYBASE  transactions  are  handled  at 
the  DBPROCESS  level  MCM^AGE  ttanaarrions  are  handkd  at  the  dutahaae  connection 
level  but  each  gdi  query  channel  maps  to  a  sepanie  dattbase  connectian.  The  channel 
argument  is  ignored  Cor  (MIACLE  and  POSTGRES. 

traB_aaBM  The  transaction  name  of  the  transaction  to  be  rolled  back.  This  argument  is  only  valid 
for  SYBASE,  which  allows  nested,  named  transactioos. 

DUGNOSnCS 

gdi  jollbackO  returns  one  of  the  following  status  values. 

GDI_SUCCESS 

Rollback  succeeded. 

GDI.FAILURE 

Rtdlback  failed:  poasiMy  the  coonectioo  dropped. 

FILE 

gdi_tranx 
SEE  ALSO 

gdi_bcgin_tran(3),  gdi_CQaiBiit(3),  gdi_aaTcpoiBt(3) 

AUTHOR 

B.  MacRfachie,  SAIC  Geophysical  Systems  Operatioo,  Open  Systems  Division 


Sim  Release  4.1 


Last  change:  12/27/93  (v20.2) 
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GDI_SAVEPCMNT(3) 


C  UKIARY  FUNCnC»IS 


GDI_SAVEPOlW(3) 


NAME 

gdi_savq)oint  -  set  a  savepoiiit 

SYNOPSIS 

ftadHde  libidLfe'' 

iat 

■di_savepoiat  (oou,  diMao,  saaaM) 

dbCoaa  •coaa;  /•  (i)  databaae  connectinn  */ 

fait  chaaao;  /*  (i)  channel  number  •/ 

char  «aaaBM;  h  (i)  savepoint  name  •/ 

DESCRIPTION 

A  database  transaction  is  a  satrmmt.  or  aaiwnmti,  treated  as  an  atomic  wiL  gdi_savqxraiO 
identifies  a  point  in  a  transaction  to  which  a  process  can  later  taObttk  with  the  rollback  to  savepoint 
savepointjutme  statement. 

To  rollback  to  a  named  aavqioint,  the  proceas  most  build  a  text  string  containing  the  entire  SQL  state¬ 
ment.  dien  execute  die  statement  with  a  call  to  gdi^submitO- 

A  call  to  gdi_rollbadt0  of  gdi^commitO  negates  all  savepoints. 

Transactioo  management  is  implemented  sli^uly  diffaeody  fat  all  the  databases  the  gdi  supports. 
ARGUMENTS 

conn  The  database  connector 

channo  Setting  a  savqioint  involves  a  S(H>  command  that  must  be  executed  on  a  channeL  For 
SYBASE,  it  sets  a  saveptmt  only  for  activity  on  diat  channel  since  tnmsactions  are  han¬ 
dled  at  the  DBPROCESS  leveL  not  the  database  connection  level  For  CXIACLE  it  sets  a 
savepoint  at  the  tOtCoon  level  became  transactions  are  at  the  database  connection  level. 
MONTAGE  and  POSTGRES  currently  do  not  $uppon  savepoints. 

DIAGNOSTICS 

gdi^savepointO  returns  one  of  the  following  stahis  values. 

GDI_SUCCESS 

Savepmnt  succeeded. 

GDI_FAILURE 

Savqxnnt  failed;  possibly  the  connection  dropped. 

PILE 

gdi^tmx 
SEE  ALSO 

idi_coauntt(3).  gdl_rallback(3).  cdijMbmM(3} 

AUTHOR 

B.  MacRitchie.  SAIC  Geophysical  Systems  Operation,  Open  Systems  Division 
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GDI_SET_DBOPTION( 3  )  C  LIBRARY  FUNCTIONS  GDI_SET_DBOPnON ( 3 ) 


NAME 

gdi_set_dbopiioii  -  Set  or  clear  a  daiahaap  option 

SYNOPSIS 

AKlude  "HbgdLb* 

iat 

gdijMt  jdboption  (cobb,  chsBBo,  optiOB,  settiBg) 
dbCou  /*  (0  database  connection  «/ 

iBt  chBBBo;  /*  (i)  channel  number  */ 

dbOptioB  optioo;  h  0)  option  to  be  set  */ 

char  ^setting;  /*  (i)  value  to  aet  option  to  •/ 

DESCRIPTION 

Various  optioos  Buy  be  aet  by  the  application  through  gdi_aetjdboptioiiO.  An  o^Mion  may  be 

cleared  or  aet  to  deCault  be  calling  gdi_aet_db(VliooO  with  a  NULL  setting.  Some  options  are  sMtable 
at  dw  channel  level 

Most  options  are  qiecific  to  a  Aaiahaaf  vendor.  If  an  qjplication  attempts  to  set  an  option  that  is  not 
applkaUe  to  the  database,  a  warning  is  issued  but  otherv^  the  action  is  ignored. 

The  state  of  a  <tataiiaat>  option  may  be  ascertained  throi^  gdi _get_dboption(3).  Sonte  t^ons,  such  as 
GDT_PRO_C,  are  not  aettabk  but  their  states  may  still  be  retrieved. 

ARGUMENTS 

COBB  The  database  connector. 

chaBBO  The  channel  number,  choniio  is  ignored  by  options  that  are  set  at  the  connector  level, 
option  TIk  option  to  be  set  or  cleared. 

setting  A  string  oontaining  the  value  to  set  the  option  to.  If  setting  is  a  NULL  or  empty  string, 
the  option  is  cleared  or  set  to  the  default  value. 

OPTIONS 

The  following  options  may  be  sec 
GDI_AUTO_COMMIT 

Oracle.  Set  auto  commit  on  or  off  (”1”  or  "0").  Auto  commit  is  off  by  default  and  is  set 
at  the  connection  level  Setting  auto  commit  on  causes  each  database  statement  to  be 
automatically  committed  as  soon  as  it  is  executed. 

GDI^CONnG 

Montage,  Postgres,  Checks  for  existence  of  GDI  database  sqtport  objects.  If  set  to 
GDIjCC^IFIGjCHECK.  returns  GDI^FAILURE  if  objects  do  not  exist.  If  set  to 
GDIjOONFIG_INSTALL,  tries  to  crettt  the  objects  if  they  do  not  already  exist  If  set 
to  Gbl_C(VII^_REMOVE,  removes  GDI  objects. 

DIAGNOSTICS 

gdi_set_dboptionO  returns  one  of  the  following  status  values; 

GDI_SUCCESS 

Operation  succeeded. 

GDI^FAILURE 

Operation  failed;  possibly  the  cormection  dropped. 

FILE 

gdi_optioox 
SEE  ALSO 
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GDI_SBT_DBOPnON(3)  C  LIBRARY  FUNCTIONS  GDI  SET_DBCH>TION(3) 


AUTHOR 

B.  MaAiichie.  SAIC  OMphytical  SyMmi  Opemioo,  Open  Systems  Di^osion 
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NAME 

gdi_skq>  -  sleep  a  landoin  number  of  seconds 

SYNOPSIS 

ffadwk  "HbfdLh" 

void 

fdijricep  (■az_ale(p) 

int  ■ux_alecp;  h  (i)  maximum  number  of  aeconda  to  sleep  */ 

DESCRIPTION 

gdi_sleepO  sleeps  a  landom  number  of  seconds  (bat  does  not  exceed  max_sleqf  seconds.  The  sleq)  is 
random  so  processm  ptoging  the  same  resource  win  become  de-synchronized  and  retry  at  differem 
times  (used  by  gdi _getjcouniBrO.  for  example). 

ARGUMENTS 

max_alcep  The  maximum  number  of  seconds  to  ever  deep.  If  set  to  0.  does  not  sleep. 

FILE 

gdi_sleq)x 

SEE  ALSO 

gdi _fet_coaBtcr(3) 

AUTHOR 

Jean  T.  Anderson,  SAIC  Geophysical  Systems  Operation,  Open  Systems  Division 
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C  LIBRARY  FUNCn€»4S 


GDI_SUBMrr(3) 


NAME 

gdi_subaiit  -  submit  •  daiabMB  command 

SYNOKIS 

fiaciiMk  *libfdU" 

iat 

|di_Mibmtt 
dbCou 
char 
iBt 

dhCoMtr 
dhObj 

DESCRIPnON 

gdt_aidimitO  scads  a  command  lo  dm  rtiiibar  to  be  eamcamd.  The  results  of  the  command, 

inchidiiig  status,  enon,  and  tqdes,  if  any.  wiS  be  maamd  in  the  rtsuks  atnictnre. 

The  commands  must  be  smoen  in  the  native  language  of  the  target  database.  The  commands 

must  be  complete  and  syntactically  conect 

For  (MIACLE  Hafti— b  coonectioas.  the  types  at  commands  that  ouqt  be  executed  include  army  fetches, 
insens,  updates  and  deletes  without  bind  variables.  DDL  commands  such  as  cream,  drop  or  alter  taUe, 
commit,  and  rotOmck  can  also  be  done  with  gdi  submitO.  Timeouts  can  occur  while  waiting  for  DDL 
locks. 

Sam|de  commands  allowed  for  (XtACLE  and  SYBASE  connectiooB  include: 

"select  *  from  anival” 

"aelea  sta,  chan  from  anival* 

"aelea  oxrid,  amtid,  oJat,  oJon,  o.depth,  atime,  a.phaae, 
ar Jime,  araTimmh,  ar Jlow  from  assoc  a,  anival  ar, 
origin  o  where  aAid^.aiid  and  ajridimr jrid* 

"select  countf*)  from  origin,  otigerr” 

"SELECT  ajta,  a.time,  b.w^  alddate 

from  stable  a,  dyn  b  where  aja  «  b  Jta" 

"adea  max(ata),  max(time),  min(ari^  from  arrival  where  arid  in 
(select  arid  from  assoc  udim  arid«3679)" 

"update  anival  set  arid  •  5  admre  arid  *  T 
"delete  from  arrival  where  arid  ■  1234" 

"select  *  from  arrival  irimre  1«2*  »>  perfixms  a  describe 

Sample  (XtACLE  specific  commands  allowed  include: 

"select  siddev(y)  stdjr  from  datamatrix" 

"create  able  my_airival  as  select  *  from  arrival" 

"iuaen  huo  myttMe  (sta,  time,  wfid,  Iddam  )  valtms(  ’NRAO’,  87654321.99, 1(X)1, 
TO_DATEC19920527  1721:59’,  ’YYYYMMDD  HH24:MI:SS’)  )" 

Saaqile  SYBASE  specific  commands  allowed  inclnde; 

"aeka  *  into  newtaUe  from  oldtable"  f*  cream  table  •/ 

"insert  into  mytaUe  (sta,  time,  wfid,  Iddam  )  values  (  ’NRAO’,  87654321,  1001,  getdateO)” 

"inaett  into  mytaUe  (Idttam )  values  ( ’Oct  15  1993  3.'06:0’ )" 

"inaen  into  mytaUe  (Iddam  )  values  (  ’Oct  IS  1993  3.*08K)PM’ )" 


aBax_rscoiris; 


**resuHs; 


/•O) 

/•O) 

/•a) 

/•0)m>le 
/•(o)dbOl^j- 


•/ 

!)•/ 

of  records  to  fetch  */ 

•/ 

enors,daa«/ 
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Calculated  ctdumns  should  be  named  for  SYBASE  or  the  column  name  will  be  NULL,  for  example: 
"select  niax(keyvalue)  'max  key*  from  lastid* 

For  ORACLE  Version  6  database  oonnectioos,  gdi^submitO  automatically  uses  a  default  date  mask, 
'YYYYMMDD  HH24:MI:SS’,  for  columns  with  dMabasc  type  "date”.  For  ORACLE  Versimi  7.  the 
date  mask  may  be  specified  by  the  user.  If  a  to_charO  coovetskm  is  used  for  a  date  column,  the 
column’s  data^pe  becomes  "string"  and  is  no  longer  recognized  as  a  date. 

After  a  command  whidi  changes  the  contents  of  the  database  completes  successfully.  ORACLE  users 
should  call  CXtACLE  gdi_oominitO  to  commit  the  transaction.  The  user  is  also  responsiUe  for  calling 
gdi_obj_destroyO  to  free  memory  allocated  for  results. 

SQL  commands  requiring  bind  variables  are  not  imiriemented  for  CXIACLE  or  SYBASE.  For  example; 
delete  from  table  where  id  « :e 

Other  SQL  and  S(^«Plus  commands  not  imidemented  are: 

define 

describe 

@sqlscript 

spool 

set  timing  on 
colunui  fonnat 
list 

Although  gdi_8ubmit0  does  not  execute  the  describe  command,  descriptions  of  the  attributes  may  be 
obtained  in  the  column  definitkns  of  the  dbObj  structure  resulting  from  the  query  below: 

select  •  from  odile  where  1«2 

ARGUMENTS 

conn  The  database  connector. 

caid_batch  A  NULL  terminated  string  containing  any  database  command  or,  for  SYBASE  and 
MC^fTAGE,  a  batch  trf  commands.  For  instance,  insert  commands  of  the  form  "insert 
into  tables  (list  of  values)"  may  be  submitted  using  this  fimctioa  Commands  that 
select  data  from  the  database  will  be  bandied  using  array  fetches  for  ORACLE.  The 
dam  will  be  returned  in  the  results  argument 

■ax_rccord8  This  qtecifies  the  maximum  number  ai  records  that  may  be  fetched  from  the  database. 

All  records  wiO  be  fetched  if  max^records  is  set  to  -1.  If  max^records  »  0,  the  default 
maximum  MAXREC  is  returned,  maxjecords  only  applies  to  fetches. 

constr  Ibis  is  die  tuple  constructor,  which  specifies  die  functions  diat  build  the  tiqiles  for  the 

results  argument  Default  constructoR  are  provided  in  libgdLh.  The  GDI^DEFAULT 
constructor  can  be  used  when  calling  gdi_submitO.  unless  die  user  wanR  to  define 
different  functions.  Adifitional  constructotslnclude  GDI_TURBO  and  GDI^SDI. 

rcaalts  A  dbObj  structure  created  by  gdi_,submitO>  It  contains  status,  enon  and  other  results 

of  the  database  oommand.  If  the  command  resulted  in  being  fetched 

from  the  database,  results  also  contains  the  database  tuples.  For  SYBASE  and  MON¬ 
TAGE,  resuUs  may  be  a  linked  list  of  dbObfs,  one  for  each  command  in  the  command 
batch. 
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The  fields  in  a  4K>fiy  are  described  below: 

liiples  This  field  is  the  poinier  to  the  flnictiire  containing  data  tuples,  if  any. 
njuples  HjupUis  is  the  number  of  aq)les. 

coljhrf  This  field  is  a  pointer  to  a  null  tenninated  army  of  dbColD^  structures,  containing 
column  definitions.  There  is  one  column  definition  structure  for  each  ccfiumn  in  die  data¬ 
base  query. 

query  This  is  a  null  terminated  striitg  containing  the  database  query  or  command. 

rowsjfiected  This  is  the  number  of  daiahaari  rows  afiCected  by  the  qpety  or  command.  In  the  case  of  a 
fetch,  the  number  of  rows  afEected  is  the  same  as  the  number  trf  nqides  fetched. 

andjuun  When  a  blodc  of  multiple  commands  is  submitted  to  gdi_submiiO.  cmdjuun  is  the 
number  of  the  command  within  the  Mock.  Initially,  only  SYBASE  connections  will  han¬ 
dle  mult^  commands. 

more  jaws  If  a  database  command  resoUs  in  more  sows  than  were  requested  by  die  value  specified 

in  maxjecords,  this  field  indicates  that  additiooal  data  tu|des  are  avrilaUe. 

coHstructor  The  constructor  consists  of  function  pmoters  and  flags  that  specify  the  structure  of  the 
tiqiles  and  the  tiqile  container. 

next  When  a  Mock  of  commands  is  submitted  to  the  database,  a  dbObj  is  associated  with  each 

command,  nextybj  points  to  the  dbObj  cotreaponding  to  the  next  command  in  the 
block. 

prev  otj  prev  obj  points  to  the  dbObj  corresponding  to  the  previous  command  in  a  command 
Moct 

The  infonnatioo  and  fields  in  a  dbObj  should  never  he  accessed  directly.  The  GDI  provides  macros  and 
functions  to  access  the  data. 

The  following  macros  are  provided: 

GDI_OBJJNUMjnjPLES  Get  the  number  of  tuples  in  a  dbObj. 
GDI_OBJ_ROWS_AFFECTED  Get  the  number  M  rows  affected  by  the  command  in  a  dbObj. 
GDI_OBJ_Q1JERY  Get  the  database  query  in  a  dbObj. 

GDI_(MJ_CMD_NUM  Get  die  command  number  with  the  command  batch. 

GDI_(MU_M(HlE_ROWS  Get  the  more  rows  flag  fiom  a  dbObj. 

GDI_QBJ_STATUS  Get  the  command  status  fiom  a  dbObj. 

GDI_OBJ_TUPLES  Get  the  tuple  container  structure  fiom  a  a  dbObj. 

GDI_OBJ_CONSTRUCT(Ht  Get  the  poinier  to  the  tqfle  constructor. 

GDI_OBJ_C(H.i_DEFS  Get  the  poinier  to  die  array  of  column  definitions. 

GDI_OBJ_COL_DEF  Get  the  poinier  lo  a  specified  column  definition,  given  the  column 

number  in  the  command. 

GDI_OBJ_COL_NAME  Get  the  name  of  a  cMumn  in  a  dbObj,  given  the  column  number 

widiin  die  command. 

GDI_OBJ_COL_CTVPE  Get  the  C  Qrpe  td  a  column  in  a  dbObj,  given  the  column  number 

within  the  command. 

GDI_OBJ_COL_PRECIS10N  Get  the  database  precisioo  ot  a  column  in  a  dbObj,  given  the 

column  number  widiin  the  command.  Precisian  is  only  valid  for 
ORACLE  data. 

GDI_OBJ_COL_SCALE  Get  the  database  scale  of  a  colunm  in  a  dbObj,  given  die  column 

number  within  the  command.  Scale  is  only  valid  for  ORACLE 
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data. 

GDI_OBJ_COL_MAX_STRLEN  Get  the  maximum  length  of  a  ttiing  ccdumn  in  a  dbObj,  given  J.e 

mlimm  tmwifyr  within  the 

GOI_OBJ_COL_MAX_ARRLEN  Get  the  maximum  length  of  an  anay  othimn  in  a  dbObj,  given  the 

column  number  within  the  comm^.  Anay  columns  are  only 
created  by  POSTGRES  queries. 

GDI_OBJ_COL_DBTYPE_S  Get  the  airing  iqaeaentation  of  the  database  type  of  a  column  in  a 

dbObj,  given  the  column  number  within  the  command. 

GDI_(W_ALLOW_NULL  Get  the  aihwjudl  flag  or  a  column,  given  the  column  number  in 

the  command. 

The  fimctioos  provided  include; 

gdijobJ_Biui_cohiBiBaO  Cakulatr.  the  number  of  cohmms  in  a  dhOby.  Returns  number  of 

columns  if  aucoessfiiL  *1  if  fmlure. 

gdi_obJ_valucO  Return  a  pointer  to  a  database  value,  given  a  dbObJ,  a  tuple  number 

and  a  column  number.  The  qsplication  must  cast  the  pointer  to  the 
correct  C  type  to  access  the  d^ 

gdijDbj_fiiid_valne  Return  a  pointer  to  a  database  value,  given  a  dbObJ,  a  uiple  number 

and  the  oohuno  name  instead  of  the  column  numbw. 

fdljobjjcoi_fladjcoljdef0  Return  the  number  of  a  column  in  a  dbObj,  given  the  column 

name. 

gdi_obJ_col_BuaiO  Return  the  definition  of  a  column  in  a  dbObj,  given  the  column 

name. 

DIAGNOSTICS 

gdi_subiiutO  returns  one  the  following  status  values: 

GDI_SUCCESS 

Command  executed  successfully. 

GDI_FAILURE 

Not  connected  to  datalwar  or  enor  executing  command. 

FILE 

gdi_submitjc 

NOTES 

Multiple  command  batches  are  not  implemented  yet  for  MONTAGE  and  SYBASE. 

SEE  ALSO 

VUjctNUlitP),  idl_objjdcstroy(3),  ■di_priBtjeoldefli(3),  idi_priBt_dbohJ(3),  gdi j>riBt_taples(3) 

AUTHOR 

B.  MacRitchie,  Mari  Mortell,  K.  Garcia,  SAIC  Geophysical  Systems  Operation,  Open  Systems  Division 
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NAME 

gdt.ince  -  tum  daiabwe  tncing  oo  or  off 

SYNOPSIS 

SiMbMk  HbfdLh" 

iat 

fdijiraoe  (dbcoaB,  Male,  fileaaaM) 

dbCoaa  *caBa  h  (t)  dettliaie  ccmwicior  •/ 

iat  Male/*  0)  TOUE  or  FALSE  */ 

dur  *lleaai^*  (0  anae  of  ik  */ 

DESCRIPTION 

gdi_tiaceO  eaables  or  duebles  ^«***— *  ttadi^  If  the  daiabaee  connociioB  is  lo  a  SYBASE  dMabase. 
tbcliaces  m  dumped  to  a  fik  specified  b3r,^toM8ae. 

ARGUMENTS 

eoaa  Tbe  database  coaaector. 

state  TRUE  10  tuia  oactag  oa.  FALSE  to  tun  iiaciag  off. 

fikaaoM  Output  fileaame  (SYBASE  oaly).  May  be  a  auU  or  eaqay  striag. 

DIAGNOSnCS 

gdi.tmceO  letuns  one  of  die  foOowiag  status  values. 

GDI_SUCCESS 

Tbeoe  successfully  eaabied  or  disabled. 

GDI^FAILURE 

gdi_traceO  teiled;  possiUy  the  oooaectioo  dropped. 

PILE 

gdi_trace£ 

AUTHOR 

B.  MacRitchie,  SAIC  Geophysical  Systems  Opoatioo.  Open  Systems  Divisioo 
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NAME 

on_sqlca_error  -  stores  S^^A  enor  in  the  connoctor 

SYNOPgS 

iMiidc  "IbidU'' 

«iMtade  ’ora.proC^'' 

tad 

oni_sqlca_cnror  (con,  ptr_sqlca.  str) 

dbCou  ~  •con;  ~  /*  (i)  dniMse  conneciion  •/ 

street  sqlcn  *plr_sqlcsi:  h  0)  S(H£A  */ 

char  *strr  /*  custom  string  V 

DESCRDPTION 

an^sqlcajefToiO  stores  the  status  of  a  SQL  staSfmmt  execated  by  a  FRCMT  call  baaed  on  the  contents 
of  dm  S(^  Communication  area  (S(HX!A).  Ihe  databaar  connection  must  be  opened  by  ofacle_openO 
to  execute  PROC  ntutines. 

ARGUMENTS 

con  The  datahnsc  connector, 

ptr  jH|ka  Pointer  to  the  S^X^A. 

atr  Customized  enor  string. 

FILE 

gdijeirorx 

NOTES 

Note  that  this  is  an  ORACLE-spedfic  routine  higidighted  here  for  users  who  wish  to  link  their  own 
FRO*C  routines  with  hbgdLa. 

SEE  ALSO 

orackjipcn(3) 

AUTHOR 

Jean  T.  Andenon,  SAIC  Geophysical  Systems  Opentioo.  Open  Systems  Division 
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NAME 

gdi^ckiae  -  clow  die  qKdfied  d<rtiwr  connoction 

SYNOPSIS 

MMhMte  "idi.rn^'' 


iatticr  Auctioa  |di_cioM  (oou) 

iatafer  cou  (Q  dwabaae  conneciion 

DESCRIPnON 

gdi^cloaeO  cloaes  a  connoction  to  the  databaw  md  finea  the  ijaabair  connection  stmcune,  dbCoiut, 
aaaociatcd  with  the  com  parameter. 

ARGUMENTS 

€i«B  The  databaae  coonecdon  handle  (tf  the  connection  to  be  cloaed 

DUGNOSnCS 

gdi_cloaeO  retmns  one  of  the  following  Ratns  vahies. 

GDI_SUCCESS 

Connectioo  soocessfiilly  cloaed 

GDI^FAILURE 

Not  connected  to  dathbaae. 

viLE 

gdi_f77jcannx 
SEE  ALSO 

gdijopcnO),  tdi_opca(30 

AUTHOR 

R  Turner,  SAK^  Geopbyiicai  Systems  Operatkn.  Open  Systems  Division 
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NAME 

gdi_eiior_get  -  retrieve  error  mfonnaiioo  fiom  ibe 
SYNOPSIS 


iiMlMle' 

’gdi_rnji" 

anbrontiM  gdi^crror  jtt  (eoa 

m,  errcode.  errtext.  maitrxt.  states,  severity) 

intator 

conn 

(i)  database  connection 

intcfcr 

errcode 

(o)  specific  error  code 

character 

errtext 

(o)  error  text 

integer 

maxtext 

(0  length  of  emext  variable 

integer 

states 

(o)  general  stuns 

integer 

severity 

(o)  aevetiqr 

DESCRIPnON 

gdi  error _getO  retrieves  error  infonnation  from  the  connector. 

ARGUMENTS 

conn 

The  database  connection  handle.  If  the  handle  is  set  to  DB_NOCONN,  then  global  error 
information  is  retrieved. 

cmcode 

Error  code. 

errtext 

Message  text  for  the  error  code. 

maxtext 

Sire  of  the  errtext  string,  cootnds  how  much  text  may  be  copied  into  the  user’s  emext 

variable. 

states 

GDI^SUCCESS  or  GDI_^FAILURE. 

severity 

GDI_N(%RRCXI.  GDI^FATAL,  or  GDI^WARNING. 

SAMPLE  CODE 

See  test  stubs  in  IibsicAibgendbAest/(aracle  I  postgres). 


FILE 

gdi_f77jerror.c 
SEE  ALSO 

rUjeiTor jet(3),  fdi_ciTor_iBit(30 
AUTHOR 

R  Turner,  SAIC  Geophysical  Systems  Opentkm,  Open  Systems  Division 
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NAME 

gdi_eirar_Biit  -  inirialiTf.  emr  handling  flagt 

SYNOPSIS 

ftectade  "idi.rTTA" 

mbraatlM  tdi_crror_Ut  (dbcoaa,  dtbt>  throhold,  raerr«dl»  rcacrvcdl) 
iatefcr  dkiCoaa  (i)  (latahMt  coniiBction 

iMctcr  ddMl  (0  GDI  IXBUG  OFF.  GI»  DEBUG  CM.  GDI  I^UG  VERBOSE 

iMcfcr  thNihdd  (0  GDI^WARNDki  or  GDfFATAL  ~ 

taittfcr  rcMTvcdl  (i)  not  «ed 

iatctar  rcicrvedl  ^ootOMd 

DESCRIPTION 

Eiron  mt  handled  on  a  connection  by  connection  bniia.  gdijBnDr_inilO  inirialiaea  the  debug  and  thres¬ 
hold  flags  for  a  datahaae  connector,  debug  contiols  ofitional  oui^  of  enots  to  stderr.  threshold  sets 
the  level  of  enor  or  wanting  that  is  oeaied  as  a  foilore  by  the  GDL 


ARGUMENTS 

The  databesf  connection  handle. 

debog 

GDI_DEBUG_OFF  (FALSE)  by  defoulL  If  set  to  GDI_DEBUG_ON  (TRUE),  errars  are 
output  automatically  to  stderr.  If  set  to  GDI_IXBUG_yERBOS,  non-enor  debug  mes¬ 
sages  are  ouqwt  automatically  to  stderr. 

threshold 

Sets  the  thieshold  at  which  an  enor  or  wanting  canaes  a  GDI_FAILURE. 
GDI_WARNING  causes  all  wantings  and  enots  to  be  treated  as  foiliaes. 
GDI_FATAL  causes  only  fatal  enon  to  be  treated  as  fitihires. 

<u.  W. 

o  o 

<  < 

rcaervcdl 

Reserved  for  future  use. 

reserved! 

Reserved  for  future  use. 

FILE 

gdi_f77jenor.c 

SEE  ALSO 

idi_crrorj|etC3f),  •dijerror_Ut(3) 

AUTHOR 

R  Tamer,  SAIC  Geophysical  Systems  Opecation,  Open  Systems  Division 
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NAME 

gdi _Eet_account  >  get  dattbeae  account  name  from  database  comiecinr 

SYNOPSIS 

iinclade  "gdl.fTTA" 

iat 

gdi _get_acconat  (conn,  acconat) 

dbCona  *coBn;  t*  (i)  databaac  connection  */ 

char  *aocoont;  h  (o)  account  name  */ 

DESCRIPTION 

gdi _get_accountO  gets  the  database  account  name  from  the  tiatabasr  connector. 
ARGUMENTS 

conn  The  ^  connection  handle, 

aoeonnt  Database  account  name  is  filled  in  by  this  routine. 
DIAGNOSTICS 

gdi  jgetjaccountQ  returns  one  of  the  following  status  values. 

GDI.SUCCESS 

Routine  succeeded. 

GDI_FAILURE 

Not  connected  to  dattdMse. 

FILE 

gdi_f77_conac 
SEE  ALSO 

gdi jct_dafabaac(30.  gdi jgct_nodc(30 

AUTHOR 

B.  MacRitchie.  SAIC  Geophysical  Systems  Opeiatioo.  Open  Sy«ems  Division 
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C  LIBRARY  FUNCnCX^S 


ODI_GET_DATAB  ASE  (  3  ) 


NAME 

gdi  js/eijiataibuc  -  get  databaae  name  from  <y)f|ii«rtnr 

SYNOPSIS 

ifadiide  ”idi_f77^" 

fait 

gdi _fet_databaae  (cou,  databaae) 

dbCoBB  «caBa;  /•  (i)  database  connectioo  •/ 

cbar  •database;  /•  (o)  databaae  aame  •/ 

DESCRIPTION 

gdi_get_databaseO  gets  ibe  database  name  Dam  die  datbbasr  cconector. 
ARGUMENTS 

COBB  The  database  conneciien  handle, 

database  Databaae  name  is  filled  fai  by  due  routiiie. 

DUGNOSnCS 

gdi _get_databaseO  retuns  one  of  the  following  stams  valiies. 

GDI_SUCCESS 

Routine  succeeded. 

GDI_FAILt)KE 

Not  connected  to  database. 


FILE 

gdi_f77jcoan.c 
SEE  ALSO 

gdi ^_aceonBt(30.  gdi jHjaodeOt) 

AUTHOR 

B.  MacRitcbie,  SAIC  Geophysical  Systems  Operatiao,  Open  Sys^ms  Division 
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NAME 

gdi jget_iiode  -  get  database  node  name  from  dambaaei  connector 

SYNOPSIS 

ttadnde  "■di.rTTA" 

bit 

gdij|et_Mdc  (conn,  node) 

dbCona  *conn;  /•  (i)  /fatahaMi  connection  */ 

char  *aode;  /*  (o)  node  none  */ 

DESCRIPTION 

gdi _get_nodeO  gets  the  database  node  name  from  the  database  connecter. 
ARGUMENTS 

conn  The  database  coonection  handle. 

node  Database  node  name  is  filled  in  by  this  routine. 

OUGNOSneS 

gdi _get_nodeO  returns  one  of  the  following  status  values. 

GDI_SUCCESS 

Routine  suerfedrd. 

GDI_FAILURE 

Not  connected  to  database. 

FILE 

gdi__f77jCOiui.c 
SEE  ALSO 

gdi _fet_acaiant(3f),  gdi,jct_databaae(3f) 

AUTHOR 

B.  MacRitchie.  SAIC  Geophysical  Systems  Opetatioa,  Open  Systems  Division 
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MISC.  REFERENCE  MANUAL  PAGES 


GDI_INrr(3f) 


NAME 

gdi_imt  -  initialize  the  GDI 

SYNOPSIS 

SiMtodc  "■di.fTTJ” 

tarttfcr  fiuctin  fdl.lMl  (appMM.  fdlhoMe) 
chvactcr  appnaaif  (i)  appHoiion  name 

character  pdihorac;  /*  0)  OIK  home  diiectary*/ 

DESCRIPnON 

fdi_init0  initializea  the  GDI. 

ARGUMENTS 

appaaf  Application  name  (actual  name  of  the  executable). 

fdlhouM  Directory  where  GIK  is  inaalled  The  GDI  aearehea  fdihomeAib  for  the  GDI  vendor 
interface  libnries  to  be  dynamically  located  If  fdi^mitO  has  not  been  called  or  if 
gdihome  is  an  empty  string.  **”.  then  the  GDI  will  use  the  environment  variable, 
GDDiOME. 

DUGNOSnCS 

gdi_initO  letunis  one  of  the  ftdlowing  status  values. 

GDI_SUCCESS 

GDI  successfolly  initialized 

GDI_FAILURE 

Failure  in  initialization.  possiUy  the  apfdication  name  was  invalid. 

FILE 

gdi_Iinkx 

AUTHOR 

H.  Turner,  SAK^  Geophysical  Systems  Operatian,  Open  Systems  Diviskm 
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GDI_MAP(3f) 


NAME 

gdi_iiuv  -  manage  idatioMhips  between  PCXCIRAN  dam  and  gdi  dam 

SYNOPSIS 

«iaclade  *idi_r77A" 


0)  rtitahar  connection 


(i)  Aaf  It— ^  wuMMirtiAn 

(0  map  10  cloae 


®  datahaan  conneciion 
(0  map  lodeaaoy 

integer  ftwction  gdijadd_Bup_ield  (coan,  aup,  coiaM_aamc,  data_addr,  dam_tjpc,  itriBg_lmi,  arrayjen) 


integer 

conn 

(0  Hatyh— ft 

integer 

Bup^U 

^  map  to  add  cohimo  to. 

character 

cohunn^naBM 

(i)  name  of  die  dambaae  column 

integer 

datejadite 

(j)  name  of  the  drstination  PCXITRAN  array 

integer 

dataj^pe 

^  dam  type  of  deatinatinn  array 

integer 

striBig_kn 

(0  length  of  destination  string 

integer 

DESCRIPTION 

airay^kB 

(0  length  at  destination  array 

The  GDI  Map  fimctians  aUow  the  wlicaciiQo  to  build  a  Map  which  contains  a  deaciipiion  of  the  FOR¬ 
TRAN  output  variables  for  the  dam  returned  from  a  database  <|iiery.  Each  column  in  the  query  is 
mapped  to  a  PCKTRAN  anay  on  a  aoe-ttM»e  basis.  The  applies^  builds  a  Map  and  then  passes  the 
Map  ID  to  gdi_aabmitO  along  widi  die  dambnse  qfiay.  gdi_sobaiitO  fills  the  FCKTRAN  output  arrays 
as  specified  by  the  Map.  Each  query  that  retnnis  dam  req^ies  a  valid  Map.  Mult^  mqis  may  be 
created.  Maps  may  be  reused  by  subsequent  queries.  Whm  the  Map  is  no  longer  needed,  it  may  be 
destroyed. 

gdi_open_mqiO  begins  a  impping  reference. 
gdi_clo8e_mapO  nods  a  mapping  reference. 

gdi  jlestroy_mapO  deallocates  the  memory  that  the  GDI  allocated  when  the  nup  was  buih.  Dam  in  the 
PCKTRANlsiays  are  not  aOected. 

gdijMld_iiup_fieldO  adds  an  dement,  a  reference  to  a  PWTRAN  output  array  and  a  query  ednmn,  to 
an^  ” 

ARGUMENTS 

Ihe  AaiaiMn^.  connection  handle. 

Bup_id  Identifies  the  map  to  use  in  the  operation.  Muh^  maps  may  be  defined. 
coInmBjaMf  The  name  of  the  dambaic  odunm  from  which  dam  wOl  be  read. 
data_addr  Ihe  PCKTRAN  variaUe  which  will  hdd  the  retrieved  data. 
dala_typc  The  dam  type  that  the  damjadtfr  variable  is. 

atiini^kn  Describes  bow  long  each  string  is  (should  the  ednmn  be  a  string  cohmm).  If  the 
d8m_Qpe  is  not  GDI_S11UNG.  then  this  parameter  dioold  be  zero  (0). 

arra7_lai  For  (KACLE,  this  variable  has  no  meaning  and  should  always  be  zmo  (0).  For 
POSTGRES,  this  varitible  indicates  the  number  of  rows  in  an  array  fetch. 


Integer  Auction  gdi_opu_map  (conn) 
integer  conn 

anbrontinc  gdi_doaejmap  (cann«  amp) 
integer  conn 

integer  iMP.id 

anbrontinc  gdi jkatrof _Bup  (conn*  amp) 
integer  conn 

integer  map^id 
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GDI_MAP(3f) 


DUGNCMTICS 

The  Map  functiaiu  letuni  one  of  the  following  atttus  values: 

GDI_SUCCESS 

The  requested  operetion  wus  perfonned. 

GOI^FAILinE 

The  requested  opeotioa  could  not  be  pesfonued.  Use  gdijenor jgetQ  to  get  enor  tnfor- 
matioo. 

FILE 

gdi_f77jnap.c 
SEE  ALSO 

tdijerror_fct(30 

AUTHOR 

H.  Timer.  SAIC  Geophysical  Systems  Opentkm.  Open  Systems  Divisioo 
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GDI_0PEN(3f) 


NAME 

gdi_ofMO  -  wtiblish  a  connection  to  the 

SYNOPSIS 

MKiMic  'idi.rn^'' 

iatefcr  Anction  |di_opai  (vendor,  aoooaat,  iMMfirard,  databaac,  aerver,  appoaoM) 

cbaractrr  voMlor  (0  databaac  vendor 

characler  accouat  (i)  databaac  account 

character  paaaword  (0  account  password 

characler  databaac  (0  database  or  machine 

character  aerver  (0  databaac  aerver 

character  appaaoM  (0  application  name 

DESCRIPTION 

gdi_opeo0  opens  a  dandwac  connection  to  the  specified  databaac  vendor.  Mor  than  one  connection 
may  be  cataMished,  including  a  mix  of  databaac  veodora. 

ARGUMENTS 

Many  of  ifaeae  porameien  may  be  NULL  depending  on  the  datahaic  vendor. 

vendor  Requiied  parameter.  Character  string  containing  the  name  of  the  «taH>hac<»  vendor. 
Cunently  supported  veodots  are  "montage”,  "oracle",  "postgres".  and  "sybase". 

account  Character  string  containing  the  dmritaae  account  or  user  name.  (XIACLE  account  names 
may  inchide  the  password  or  the  entiie  ORACLE  Vernon  6  database  connect  string;  for 
exmnple.  gdidemoigdidemo  or  gdulemo/giiulemo@t:skryimr:dev. 

paaaword  Character  string  containing  the  accoimt  password.  Mi^  be  an  empty  string, for  ORA¬ 
CLE  if  the  occoant  argument  inchides  the  password. 

databaac  Character  string  oontMing  die  datbbaac  far  MCR^fTAGE.  POSTGRES.  or  SYBASE  or  the 
S(H-*Net  connect  string  (U.,  cskrymindev)  far  (XIAaJE.  May  be  an  empty  string. 
far  CXIACLE  if  the  connect  strit^  is  incluM  in  the  accouia  argument,  or  if  either  the 
TWOJTASK  or  (XIACLE^SID  eavironment  variables  are  set.  If  an  enqtty  string  for  all 
databases  but  CXIACLE,  the  user's  default  database  is  opened. 

aerver  Name  of  the  dataliasr.  server.  Optional 
appnauM  Application  name  (only  used  by  SYBASE). 

DIAGNOSTICS 

If  the  attempt  to  opmi  a  connectioo  fails,  the  database  connection  handle,  com.  will  be  GDI  NOCONN. 

FILE 

gdi_f77_conn.c 
SEE  ALSO 

idi_close(30.  sdijipcB(3) 

AUTHOR 

R  Ttner.  SAIC  Geophysical  Systems  Operation.  Open  Systems  Divisioo 
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GDIJUBMIT(3f) 


NAME 

gdi^sdxnit  -  submit  a  daiabasr  command 

SYNOPSIS 

siMiwfe  "fdtrnj" 

lutegcr 

gdi^submlt  (coaa,  map^ld,  cmd^halch,  aua_raco«da,  nNn_iclrkvcd,  rawajalTccIcd,  ■orc_data) 

iM^cr  couT  (0*databaae  connectioo 

fartager  ■mr.U  (9  au^  id 

character  oad jMteh  ^  atnaf  conainiag  SQL  command(s) 

iatefcr  ■aa'recorda  ^  ouaimnm  number  of  lecoids  lo  fetch 

iateite  r<wr_rctrtefd  (o)  i  of  raws  letrieved 

iatefcr  roaTaffccted  (o)  i  of  rows  affected 

tefical  SMaw^data  (o)  agnals  mom  dan  in  the  danbase 

DESCRIFnON 

After  a  connection  has  been  made  to  a  database  with  fdijopeBO.  fili_aubmiiO  sends  a  database  com¬ 
mand  to  die  database  to  be  executed.  Dan  will  be  returned  as  described  by  the  mapjd. 

The  database  commands  must  be  written  in  the  native  language  of  the  target  database.  The  commands 
must  complete  and  syntactically  correct 

For  (XIACLE  datebaae  connections,  the  types  of  commands  that  may  be  executed  indnde  anay  fetches, 
inserts,  updates  and  deletes  without  bind  wiables.  DU.  commands  such  as  create,  drop  or  alter  table, 
commit  and  rollback  can  also  be  done  with  gdi^submitO.  Timeouts  can  occur  while  waidqg  for  DDL 
locks. 

Sample  commands  allowed  for  CXIACLE  conoectioos  include: 

"aelea  «  fiom  arrival'' 

"select  sta,  chan  from  arrival" 

"select  o.arid.  axid,  oJat  oJon,  oriqah,  adme,  a^thase. 
ar rime,  arjtrimuth,  ar jlow  from  assoc  a.  arrival  ar, 
origin  o  where  axniiliro.orid  and  aAri(hmr.atid” 

"select  aiddBv(y)  suTy  from  datamatiix" 

"select  coant(*)  from  origin,  origetr” 

"SELECT  ajta,  a.tiine.  b.w^  aJddate 

from  atabte  a.  dyn  b  where  ajta  ^  Jia" 

"select  maxCsta),  max(time),  mm(atid)  fiom  arrival  where  arid  in 
(select  arid  fiom  assoc  where  otid>3679)" 

"create  table  myjnrival  as  adect «  fiom  arrivd" 

"delete  fiom  arri^  where  arid  « 1234" 

"select  *  fiom  arrival  where  1^"  performs  a  describe 

For  ORACLE  Version  6  datsbaaf  caaatn^a,  gdi^aubmitO  automatically  uses  a  defiailt  date  mask, 
*YYYYMMIX>  HH24*14I:SS',  for  columns  with  dtehbnsr  type  "date".  CXIACLE  Version  7,  the 
date  mark  may  be  specified  by  the  user.  If  a  tojcharO  converaion  is  used  for  a  date  column,  the 
ccdumn’s  data^pe  becomes  "string"  and  is  no  kageTiecognized  as  a  date. 

After  a  command  which  changes  the  contents  of  die  datehnse  comfrieies  successfully,  the  user  should 
call  gdi_coamiitO  to  commit  the  tiansactioa 

ARGUMENTS 

conn  The  datahase  connection  handle,  returned  fiom  gdi  jopenO- 

casd.balch  A  character  string  containing  a  datsbasc  command.  Any  data  fetched  fiom  the  data¬ 

base  win  be  plaoed  in  FCXtTRAN  variables  specified  by  die  mapjd.  While  die  gdi  C 
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GDI  SUBMIT  (3f) 


iniafiKe  supports  executiiig  mull^le  conunaods  in  the  cmd_baich.  the  FORTRAN 
tnierbce  doa  not.  It  is  up  lo  the  piogranuner  to  «isuie  that  only  one  command  is 
executed  at  a  time. 

■uuK_recorda  This  specifies  the  maximum  number  of  records  that  may  be  fetched  from  the  database. 

All  records  will  be  fetched  if  max_rtcords  b  set  to  *1.  If  max_records  »  0,  the  default 
maximum  MAXREC  b  retunied.  maxjecords  only  applies  to  fetches. 

map_id  Thb  identifies  a  description  (tf  the  dau  varid)ie8  in  PCXtlKAN  q>ace. 

row8_afTccted  Thb  b  the  numba  of  rows  affected  by  the  query  or  command.  In  the  case  of 

a  fetch,  the  number  of  rows  afifecied  b  the  same  as  the  number  of  tuples  fetched. 

rows_rctrievcd  Thb  b  the  number  of  database  rows  reirbved  by  the  query  or  command.  In  the  case 
of  a  fetch,  the  number  of  rows  affected  b  the  same  as  tte  number  of  niples  fetched. 

BHirc_rows  If  a  /<«««»»«»  command  results  in  more  rows  than  were  requested  by  the  value  specified 
in  maxjecords,  thb  field  indicttes  thb  additional  data  tiq>les  are  available. 

DIAGNOSTICS 

gdi_submitO  returns  one  of  the  following  status  values.  Error  codes  and  messages  may  be  retrieved 

witt  gdijanr jfitQ. 

GDI_SUCCESS 

Command  executed  successfully. 

GDI_FAILURE 

Not  connected  to  database  or  error  executing  command. 

FILE 

gdi_f77_submitx 
SEE  ALSO 

fdijerrorjget(30t  gdi_niap(3f),  fdi_o|N»(3f),  gdijnibinit(3) 

AUTHOR 

R  Turner,  SAIC  Geophysical  Systems  Opoation,  Open  Systems  Division 
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NAME 

gdi_ince  -  tum  daigba»c.  tracing  on  or  off 

SYNOPSIS 

SiMtaMle  "gdi.lT?  V 

■dirantiM  tdi^tracc  (coan.  Mate*  Mwaraf) 
fartfgw  coaa  (D  daralraac  cowiecior 

iMcgcr  stMc  (0  .TRUE,  or  PALSE. 

character  flkaaMe  ^nameoffik 

DESCRIPTION 

gdi_iiaceO  enables  or  dwaMrs  daahaae  nacing.  If  the  daiahaar  connection  is  to  a  SYBASE  database, 
the  tiacet  aie  dumped  to  a  file  specified  hyfiiaume. 

ARGUMENTS 

ooaa  Ihe  database  connectioo  handle. 

state  TRUE  to  tnm  tracing  on,  FALSE  to  turn  tracing  off. 

fliraaate  CXitput  filename  (SYBASE  only).  May  be  nuU.  Le.  ". 

SAMPLE  CODE 

See  test  stubs  in  libsic/libgeotfliAest 

FILE 

gdi_f77_tracex 

AUTHOR 

R  Tomer,  SAIC  Geophysical  Systems  Operation,  Open  Systems  Diviskm 
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Appendix  A.  Bibliography 

The  following  bibliography  contains  SQL  references. 

Emerson,  Sandra  L,  Marcy  Damovsky  artd  Judith  S.  Bowman,  The  Practtcal  SQL  HaixaMok, 
Reading,  MA:  Addison-Wesiey  Publishing  Company,  1989. 

This  contains  an  exceiiwt  introduction  to  relationai  databases,  relational  database 
design,  and  the  SQL  language,  with  an  emphasis  on  Sybase  Transact-SQL. 

Hursch,  Carolyn  J.  and  Jack  L.  Hursch,  SCH.,  7?te  Structured  Query  Language,  Blue  Ridge 
Summit  PA:  TAB  Books,  Inc.,  1988. 

This  introduces  SQL  to  the  novice. 

van  der  Lans,  Rick.  F.,  Introduction  to  SQL,  Readtog.  MA:  Addson-Wesiey  Publishing  Com¬ 
pany,  1988. 

This  introduction  to  SQL  is  formulated  around  toe  creation  of  a  sports  club  database.  It  is 
geared  for  toe  novice  with  a  focus  on  ANSI  SQL  standard  queries. 

van  der  Lans,  Rick.  F.,  The  SQL  Standard:  A  Completa  Reference,  Hertfordshire,  England: 
Prentice  Hall  International  (UK)  Ltd,  1988. 

This  reference  is  a  companion  guide  to  van  der  Lans’  Mroducdon  to  SQL  It  is  much 
more  readable  than  the  ANSI  X3.135-1986  document. 
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Appendix  B.  Data  Types 

The  interface  provides  default  conversions  betvveen  database  data  types  and  C  typ^.  The 
tables  below  show  the  defaults  for  database  to  C  and  for  C  to  database  conversions.  The 
defaults  may  be  overridden  by  the  application  by  man^xjiatlng  the  column  definition  in  the  Data¬ 
base  Object  (ool.def  in  dbOt^). 


TaMe  16.  Defiuilt  Data  Converaon  *  Database  Types  to  C  Types 


OOl  Uttf  MtnutI 


Table  17.  Default  Data  Conv«rsioii  •  C  Types  to  Database  Types 
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DISTRIBUTION  LIST 


RECIPIENT 


NUMBER  OF  COPIES 


DEPARTMENT  OF  DEFENSE 


ARPA/NMRO  3 

ATTN;  Dr.  R.  Alewine,  Dr.  S.  Bratt,  and  Dr.  A.  Ryall,  Jr. 

3701  North  Fairfax  Drive 
Arlington,  VA  22203-1714 

ARPA,  OASB/Library  1 

3701  North  Fairfax  Drive 
Arlington,  VA  22203-1714 

Defense  Technical  Information  Center  2 

Cameron  Station 
Alexandria,  VA  22314 


DEPARTMENT  OF  THE  AIR  FORCE 

AFTAC/TT  3 

ATTN:  Dr.  L.  Himes,  Dr.  F.  Pilotte,  and  Dr.  D.  Russell 
130  South  Highway  AlA 
Patrick  AFB,  FL  32925-3002 

AFTAC/TT,  Center  for  Seismic  Studies  1 

ATTN:  Dr.  R.  Blandford 

1300  North  17th  Street,  Suite  1450 

Arlington,  VA  22209-2308 

Phillips  Laboratory/GPEH  1 

ATTN:  Mr,  J.  Lewkowicz 
29  Randolph  Road 
Hanscom  AFB,  MA  01731-3010 


DEPARTMENT  OF  ENERGY 


Department  of  Energy  1 

ATT  N:  Dr.  M.  Denny 
Office  of  Arms  Control 
Washington,  D.C.  20585 


1 


Lawrence  Livermore  National  Laboratory  4 

ATTN;  Dr.  J.  Hannon,  Dr.  K.  Nakanishi,  Dr.  H.  Patton, 

and  Eh*.  D.  Springer 

University  of  California 

P.O.  Box  808 

Livermore,  CA  94550 

Los  Alamos  National  Laboratory  1 

ATTN:  Dr.  S.  Taylor 

P.O.  Box  1663,  Mail  Stop  C335 

Los  Alamos,  NM  87545 

Sandia  National  Laboratory  2 

ATTN:  Dr.  E.  Chael  and  Dr.  M.  Sharp 
Division  9241 
Albuquerque,  NM  87185 


OTHER  GOVERNMENT  AGENCIES 

Central  Intelligence  Agency  1 

ATTN:  Dr.  L.  Turnbull 
CIA-OSV/R/NED 
Washington,  D.C.  20505 

U.S.  Geological  Survey  1 

ATTN:  Dr.  A.  McGarr 

Mail  Stop  977 

Menlo  Park,  CA  94025 

U.S.  Geological  Survey  1 

ATTN:  Dr.  W.  Leith 
Mail  Stop  928 
Reston,  VA  22092 

U.S.  Geological  Survey  1 

ATTN:  Dr.  R,  Masse 

Denver  Federal  Building 

Box  25046,  Mail  Stop  967 

Denver,  CO  80225 
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UNIVERSITIES 


Boston  College  1 

ATTN:  Dr.  A.  Kafka 

Department  of  Geology  and  Geophysics 

Chestnut  Hill,  MA  02167 

California  Institute  of  Technology  1 

ATTN:  Dr.  D.  Helmberger 
Seismological  Laboratory 
Pasadena,  CA  91125 

Columbia  University  2 

ATTN:  Dr.  P.  Richards  and  Dr.  L.  Sykes 
Lamont-Doherty  Geological  Observatory 
Palisades,  NY  10964 

Cornell  University  1 

ATTN;  Dr.  M.  Barazangi 

Institute  for  the  Study  of  the  Continent 

Ithaca,  NY  14853 

IRIS,  Inc.  2 

ATTN:  Dr.  D.  Simpson  and  Dr.  G.  van  der  Vink 
1616  North  Fort  Myer  Drive,  Suite  1050 
Arlington,  VA  22209 

Massachusetts  Institute  of  Technology  I 

ATTN:  Dr.  T.  Jordan 

Department  of  Earth,  Atmospheric  and  Planetary  Sciences 
Cambridge,  MA  02139 

Massachusetts  Institute  of  Technology  1 

ATTN:  Dr.  N.  Toksoz 

Earth  Resources  Laboratory 

42  Carleton  Street 

Cambridge,  MA  02142 

Mir  Lincoln  Laboratory,  M-200B  1 

ATTN:  Dr.  R.  Lacoss 
P.O.  Box  73 

Lexington,  MA  02173-0073 

San  Diego  State  University  1 

ATTN:  Dr.  S.  Day 

Department  of  Geological  Sciences 

San  Diego,  CA  92182 
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Southern  Methodist  University 
ATTN:  Dr.  E.  Herrin  and  Dr.  B.  Stump 
Institute  for  the  Study  of  Earth  and  Man 
Geophysical  Laboratory 
Dallas,  TX  75275 

Southern  Methodist  University  1 

ATTN:  Dr.  Gary  McCartor 
Department  of  Physics 
Dallas,  TX  75275 

State  University  of  New  York  at  Binghamton  2 

ATTN:  Dr.  J.  Barker  and  Dr.  F.  Wu 
Department  of  Geological  Sciences 
Vestal,  NY  13901 

St.  Louis  University  2 

ATTN:  Dr.  R.  Herrmann  and  Dr.  B.  Mitchell 
Department  of  Earth  and  Atmospheric  Sciences 
St.  Louis,  MO  63156 

The  Pennsylvania  State  University  2 

ATTN:  Dr.  S.  Alexander  and  Dr.  C.  Langston 

Geosciences  Department 

403  Deike  Buil^g 

University  Park,  PA  16802 

University  of  Arizona  1 

ATTN:  Dr.  T.  Wallace 

Department  of  Geosciences,  Building  #77 

Tucson,  AZ  85721 

University  of  California,  Berkeley  2 

ATTN:  Dr.  L.  Johnson  and  Dr.  T.  McEvilly 
Seismographic  Station 
Berkeley,  CA  94720 

University  of  California,  Davis  1 

ATTN:  Dr.  R.  Shumway 
Division  of  Statistics 
Davis,  CA  95616 

University  of  California,  San  Diego  5 

ATTN:  Dr.  J.  Berger,  Dr.  L.  Burdick,  Dr.  H.  Given,  Dr.  B.  Minster, 
and  Dr.  J.  Orcutt 

Scripps  Institute  of  Oceanogn^hy,  A-025 
LaJoUa,CA  92093 
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University  of  California,  Santa  Cniz 
ATTN:  Dr.  T.  Lay 
Institute  of  Tectonics 
Earth  Science  Board 
Santa  Cruz,  CA  95064 

University  of  Colorado  2 

ATTN:  Dr.  C.  Archambeau  and  Dr.  D.  Harvey 

CIRES 

Boulder,  CO  80309 

University  of  Connecticut  1 

ATTN:  V.  Cormier 

Department  of  Geology  and  Geophysics 

U-45.  Room  207 

Storrs,  CT  06268 

University  of  Southern  California  1 

ATTN:  Dr.  K.  Aki 

Center  for  Earth  Sciences 

University  Paric 

Los  Angeles,  CA  90089-0741 

University  of  Wisconsin-Madison  1 

ATTN:  Dr.  C.  Thurber 

Department  of  Geology  and  Geophysics 

1215  West  Dayton  Street 

Madison,  WS  53706 


DEPARTMENT  OF  DEFENSE  CONTRACTORS 

Center  for  Seismic  Studies  3 

ATTN:  Dr.  R.  Bowman,  Dr.  J.  Carter,  and  Dr.  R.  Gustafson 
1300  North  17th  Street,  Suite  1450 
Arlington,  VA  22209 

ENSCO,  Inc.  2 

ATTN:  Dr.  D.  Baumgardt  and  Dr.  Z.  I>er 
5400  Port  Royal  Road 
Springfield,  VA  22151-2388 

ENSCO,  Inc.  2 

ATTN:  Dr.  R.  Kemerait  and  Dr.  D.  Taylor 
445  Pineda  Court 
Melbourne,  FL  32940-7508 
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Mission  Research  Coiporation 

ATTN;  Dr.  M.  Fisk 

735  State  Street 

PO  Drawer  719 

Santa  Barbara,  CA  93102-0719 

1 

Radix  Systems,  Inc. 

ATTN:  Dr.  J.  PuUi 

201  Perry  Parkway 

Gaithersburg,  MD  20877 

1 

Science  Horizons 

ATTN:  Dr.  T.  Cherry 

710  Encinitas  Blvd.,  Suite  200 

Encinitas,  CA  92024 

1 

S-CUBED, 

A  Division  of  Maxwell  Laboratory 

ATTN:  Dr.  T.  Bennett  and  Mr.  J.  Murphy 

11800  Sunrise  Valley  Drive,  Suite  1212 

Reston,  VA  22091 

2 

S-CUBED, 

A  Division  of  Maxwell  Laboratory 

ATTN:  Dr.  K.  McLaughlin  and  Dr.  J.  Stevens 

P.O.  Box  1620 

LaJoUa,CA  92038-1620 

2 

SRI  International 

ATTN:  Dr.  A.  Florence  and  Dr.  S.  Miller 

333  Ravenswood  Avenue,  Box  AF116 

Menlo  Park,  CA  94025-3493 

2 

Teled3me  Geotech 

ATTN:  Mr.  W.  Rivers 

314  Montgomery  Street 

Alexandria,  VA  22314-1581 

1 

TASC,  Inc. 

ATTN:  Dr.  R.  Comer 

55  Walkers  Brook  Drive 

Reading,  MA  01867 

1 
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NON-US  RECIPIENTS 


Blacknest  Seismoiogical  Center  1 

ATTN:  Dr.  P.  Marshall 
UK  Ministry  of  Defense 
Blacknest,  Brimpton 

Reading  FG7-FRS,  UNITED  KINGDOM 

Institute  for  Geophysik  I 

ATTN:  Dr.  H.-P.  Haijes 

Ruhr  University/Bochum 

P.O.  Box  102148 

4630  Bochum  1,  GERMANY 

NTNF^ORSAR  2 

ATTN:  Dr.  S.  Mykkeltveit  and  Dr.  F.  Ringdal 
P.O.  Box  51 

N-2007  Kjeller,  NORWAY 

Societe  Radiomana  1 

ATTN:  Dr.  B.  Massinon 
27  Rue  Claude  Bernard 
75005  Paris,  FRANCE 

University  of  Cambridge  1 

ATTN:  Dr.  K.  Priestley 

Bullard  Labs,  Department  of  Earth  Sciences 

Madingley  Rise,  Madingley  Road 

Cambridge  CB3,  OEZ,  ENGLAND 

University  of  Toronto  1 

ATTN:  Dr.  K.-Y.  Chun 

Geophysics  Division 

Physics  Department 

Ontario,  CANADA 
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